<commit_before><?xml version="1.0"?>
<!--
   Copyright 2001-2004 The Apache Software Foundation

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->

<document>

 <properties>
  <title>Examples</title>
  <author email="<EMAIL>"><NAME></author>
 </properties>

<body>

<section name="Examples">
<a name="simple-example"/>
<subsection name='A Simple Example'>
    <p>
    This is a simple example to help those new to betwixt. It shows how a simple bean can be converted to
    xml and back again. A round trip, no less!
    </p>
    <p>
    In order to run these simple examples, the classpath needs to contain Betwixt and all its 
    <a href='../dependencies'>dependencies</a>. Note that any 
    <a href='http://java.sun.com/xml/jaxp/index.html'>JAXP (1.1 or later)</a> compliant parser 
    can be used to replace xerces and xml-apis. JUnit is not required to run betwixt (but is needed
    if you want to run the unit tests in CVS).
    </p>
    <p>
    This example is based around a very simple bean representing a person:
    
<source><![CDATA[
public class PersonBean {
    
    private String name;
    private int age;
    
    /** Need to allow bean to be created via reflection */
    public PersonBean() {}
    
    public PersonBean(String name, int age) {
        this.name = name;
        this.age = age;
    }
    
    public String getName() {
        return name;
    }
    
    public void setName(String name) {
        this.name = name;
    }	
    
    public int getAge() {
        return age;
    }
    
    public void setAge(int age) {
        this.age = age;
    }
    
    public String toString() {
        return "PersonBean[name='" + name + "',age='" + age + "']";
    }
}
]]></source>
    </p>
    <p>
    The basic usage pattern for writing beans using Betwixt is to create a BeanWriter, configure it 
    and then pass a bean into the <code>write</code> method. Pretty easy. 
    </p>
    <p>
    Here's a simple application which converts a person bean to xml which is then sent to <code>System.out</code>:
    
<source><![CDATA[
import java.io.StringWriter;

import org.apache.commons.betwixt.io.BeanWriter;

public class WriteExampleApp {

    /** 
     * Create an example bean and then convert it to xml.
     */
    public static final void main(String [] args) throws Exception {
        
        // Start by preparing the writer
        // We'll write to a string 
        StringWriter outputWriter = new StringWriter(); 
        
        // Betwixt just writes out the bean as a fragment
        // So if we want well-formed xml, we need to add the prolog
        outputWriter.write("<?xml version='1.0' ?>");
        
        // Create a BeanWriter which writes to our prepared stream
        BeanWriter beanWriter = new BeanWriter(outputWriter);
        
        // Configure betwixt
        // For more details see java docs or later in the main documentation
        beanWriter.getXMLIntrospector().getConfiguration().setAttributesForPrimitives(false);
        beanWriter.getBindingConfiguration().setMapIDs(false);
        beanWriter.enablePrettyPrint();
        
        // Write example bean as base element 'person'
        beanWriter.write("person", new PersonBean("<NAME>", 21));
        
        // Write to System.out
        // (We could have used the empty constructor for BeanWriter 
        // but this way is more instructive)
        System.out.println(outputWriter.toString());
    }
}

]]></source>
    </p>
    <p>
    Ths basic usage pattern for reading beans is only a little more complex. This time, you need to
    create a BeanReader, configure it, register the bean classes that the xml will be mapped to and 
    then parse should be called.
    </p>
    <p>
    Here's a simple application that converts some xml to a person bean. The bean is then converted
    to string and the result sent to <code>System.out</code>:
    
<source><![CDATA[
import java.io.StringReader;

import org.apache.commons.betwixt.io.BeanReader;

public class ReadExampleApp {
    
    public static final void main(String args[]) throws Exception{
        
        // First construct the xml which will be read in
        // For this example, read in from a hard coded string
        StringReader xmlReader = new StringReader(
                    "<?xml version='1.0' ?><person><age>25</age><name><NAME></name></person>");<commit_msg>Added extra comments to the example. Thanks to <NAME> for pointing out ways that the example could be enhanced.<commit_after><?xml version="1.0"?>
<!--
   Copyright 2001-2004 The Apache Software Foundation

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->

<document>

 <properties>
  <title>Examples</title>
  <author email="<EMAIL>"><NAME></author>
 </properties>

<body>

<section name="Examples">
<a name="simple-example"/>
<subsection name='A Simple Example'>
    <p>
    This is a simple example to help those new to betwixt. It shows how a simple bean can be converted to
    xml and back again. A round trip, no less!
    </p>
    <p>
    In order to run these simple examples, the classpath needs to contain Betwixt and all its 
    <a href='../dependencies'>dependencies</a>. Note that any 
    <a href='http://java.sun.com/xml/jaxp/index.html'>JAXP (1.1 or later)</a> compliant parser 
    can be used to replace xerces and xml-apis. JUnit is not required to run betwixt (but is needed
    if you want to run the unit tests in CVS).
    </p>
    <p>
    This example is based around a very simple bean representing a person:
    
<source><![CDATA[
public class PersonBean {
    
    private String name;
    private int age;
    
    /** Need to allow bean to be created via reflection */
    public PersonBean() {}
    
    public PersonBean(String name, int age) {
        this.name = name;
        this.age = age;
    }
    
    public String getName() {
        return name;
    }
    
    public void setName(String name) {
        this.name = name;
    }	
    
    public int getAge() {
        return age;
    }
    
    public void setAge(int age) {
        this.age = age;
    }
    
    public String toString() {
        return "PersonBean[name='" + name + "',age='" + age + "']";
    }
}
]]></source>
    </p>
    <p>
    The basic usage pattern for writing beans using Betwixt is to create a BeanWriter, configure it 
    and then pass a bean into the <code>write</code> method. Pretty easy. 
    </p>
    <p>
    Here's a simple application which converts a person bean to xml which is then sent to <code>System.out</code>:
    
<source><![CDATA[
import java.io.StringWriter;

import org.apache.commons.betwixt.io.BeanWriter;

public class WriteExampleApp {

    /** 
     * Create an example bean and then convert it to xml.
     */
    public static final void main(String [] args) throws Exception {
        
        // Start by preparing the writer
        // We'll write to a string 
        StringWriter outputWriter = new StringWriter(); 
        
        // Betwixt just writes out the bean as a fragment
        // So if we want well-formed xml, we need to add the prolog
        outputWriter.write("<?xml version='1.0' ?>");
        
        // Create a BeanWriter which writes to our prepared stream
        BeanWriter beanWriter = new BeanWriter(outputWriter);
        
        // Configure betwixt
        // For more details see java docs or later in the main documentation
        beanWriter.getXMLIntrospector().getConfiguration().setAttributesForPrimitives(false);
        beanWriter.getBindingConfiguration().setMapIDs(false);
        beanWriter.enablePrettyPrint();

        // If the base element is not passed in, Betwixt will guess 
        // But let's write example bean as base element 'person'
        beanWriter.write("person", new PersonBean("<NAME>", 21));
        
        // Write to System.out
        // (We could have used the empty constructor for BeanWriter 
        // but this way is more instructive)
        System.out.println(outputWriter.toString());
        
        // Betwixt writes fragments not documents so does not automatically close 
        // writers or streams.
        // This example will do no more writing so close the writer now.
        outputWriter.close();
    }
}

]]></source>
    </p>
    <p>
    Ths basic usage pattern for reading beans is only a little more complex. This time, you need to
    create a BeanReader, configure it, register the bean classes that the xml will be mapped to and 
    then parse should be called.
    </p>
    <p>
    Here's a simple application that converts some xml to a person bean. The bean is then converted
    to string and the result sent to <code>System.out</code>:
    
<source><![CDATA[
import java.io.StringReader;

import org.apache.commons.betwixt.io.BeanReader;

public class ReadExampleApp {
    
    public static final void main(String args[]) throws Exception{
        
        // First construct the xml which will be read in
        // For this example, read in from a hard coded string
        StringReader xmlReader = new StringReader(
                    "<?xml version='1.0' ?><person><age>25</age><name><NAME></name></person>");
{'fraction_non_alphanumeric': 0.09304612963509393, 'fraction_numerical': 0.00472115668338743, 'mean_word_length': 2.547801814375436, 'pattern_counts': {'":': 0, '<': 116, '<?xml version=': 6, '>': 114, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 26}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4790473', 'n_tokens_mistral': 2829, 'n_tokens_neox': 2726, 'n_words': 1152}