Methods for Types Generated From Schema

As you may have seen in Getting Started with XMLBeans, you use the types generated from schema to access XML instances based on the schema. If you're familiar with the JavaBeans technology, the conventions used in the generated API will be recognizable.

In general, elements and attributes are treated as "properties" in the JavaBeans sense. In other words, as you would with JavaBeans properties, you manipulate parts of the XML through accessor methods such as getCustomer() (where you have a "customer" element), setId(String) (where you have an "id" attribute), and so on. However, because schema structures can be somewhat complex, XMLBeans provides several other method styles for handling those structures in XML instances.

Prototypes for Methods in Generated Interfaces

Several methods are generated for each element or attribute within the complex type. This topic lists each method that could be generated for a given element or attribute.

Note that whether or not a given method is generated is based on how the element or attribute is defined in schema. For example, a customer element definition with a maxOccurs attribute value of 1 will result in a getCustomer method, but not a getCustomerArray method — after all, only one customer element is possible in an instance document.

Note, too, that there may be two sets of parallel methods: one whose prototype starts with an "x". An "x" method such as xgetName or xsetName would be generated for elements or attribute whose type is a simple type. A simple type may be one of the 44 built-in simple types or may be a restriction in schema of one of those built-in types. Of course, an attribute will always be of a simple type. For built-in simple types, an "x" method will get or set one of the types provided with XMLBeans, such as XmlString, XmlInteger, XmlGDay, and so on. For derived types, the "x" method will get or set a generated type.

Single Occurrence Methods

Methods generated for elements or attributes that allow a single occurrence. An element is singular if it was declared with maxOccurs="1". An attribute is singular if it was not declared with use="prohibited".

Type getFoo()
void setFoo(Type newValue)
Returns or sets the value of Foo. Generated when Foo is an attribute, or is an element that can occur only once as a child.

XmlType xgetFoo()
void xsetFoo(XmlType newValue)
Returns or sets the value of Foo as an XMLBean simple type. These methods are generated if Foo's type is defined in schema as a simpleType.

boolean isNilFoo()
void setNilFoo()
Determines or specifies whether the Foo element is nil (in other words, "null" in schema terms), meaning it can be empty. A nil element looks something like this:
<foo/>
These methods are only generated when an element type is declared as nillable in schema — it has a nillable="true" attribute.

XmlType addNewFoo()
Adds a new Foo as an XMLBean simple to the document, or returns Foo's value if one exists already.

boolean isSetFoo()
void unSetFoo()
Determines whether the Foo element or attribute exists in the document; removes Foo. These methods are generated for elements and attributes that are optional. In schema, and optional element has an minOccurs attribute set to "0"; an optional attribute has a use attribute set to "optional".

Multiple Occurrence Methods

Methods generated for elements that allow multiple occurrences.

An element may occur multiple times if it has a maxOccurs attribute set to "unbounded" or greater than 1. Attributes can't occur multiple times.

Type[] getFooArray()
void setFooArray(Type[] newValue) 
Returns or sets all of the Foo elements.
// Get an array of the all of the purchase-order elements item children.
Item[] items = myPO.getItemArray();

Type getFooArray(int index)
void setFooArray(Type newValue, int index)
Returns or sets the Foo child element at the specified index.
// Sets the value of the third item child element.
myPO.setItem(newItem, 2);

int sizeOfFooArray()
Returns the number of Foo child elements.
// Returns the number of item child elements.
int itemCount = myPO.sizeOfItemArray();

void removeFoo(int index)
Removes the Foo child element at the specified index.

XmlType[] xgetFooArray()
void xsetFooArray(XmlType[] arrayOfNewValues)
Returns or sets all of the Foo elements as XMLBeans simple types. Generated only when the Foo element is defined as a simple type.
/*
 * Returns values of all the phone child elements of an employee element,
 * where the phone element has been defined as xs:string.
 */
XmlString[] empPhones = currentEmployee.xGetPhoneArray();

XmlType xgetFooArray(int index)
void xsetFooArray(int index, XmlType newValue)
Returns or sets the Foo element at the specified index, using an XMLBeans simple type value. Generated for an element defined as a simple type in schema.

void insertFoo(int index, FooType newValue)
Inserts the specified Foo child element at the specified index.

void addFoo(FooType newValue)
Adds the specified Foo to the end of the list of Foo child elements.

XmlType insertNewFoo(int index)
Inserts a new Foo at the specified index, returning an XMLBeans simple type representing the new element; returns the existing Foo if there's already one at index.

XmlType addNewFoo()
Adds a new Foo element to the end of the list of Foo child elements, returning an XMLBeans simple type representing the newly added element.

boolean isNilFooArray(int index)
void setNilFooArray(int index)
Determines or specifies whether the Foo element at the specified index is nil.

Related Topics

Java Types Generated from User-Derived Schema Types