Home > Apache Pivot > Apache Pivot Class Instances

Apache Pivot Class Instances

BXML allows you to create your objects and set the class attributes all within a BXML document. There are a few things to keep in mind. To create an object, the element that defines the instance of your class must start with a capital letter. The BXML Serializer object will interpret XML tags that begin with a capital letter as objects.

Secondly, the serializer object requires you to specify the namespace in which the object is defined. A traditional Swing JLabel, for example, is defined in the javax.swing package. You are able to define your own custom objects as well.

For example…
Company B has created a custom object representing a Person to be used in their Java GUI. The person class has two attributes of type String: First and Last Name.  They have created getters and setters and the Person object is ready for use. In the BXML document an instance of the Person class is defined and first and last name properties are set. When a Person object is instantiated, the BXMLSerializer will populate a Person object into the Java application.

Exploring this example, lets create the Person object. Here is a class that represents our Person.


* This class represents a person object.  
package logic;

public class Person {

    private String firstName;
    private String lastName;

    public Person()
        this.firstName = "";
        this.lastname = "";

    public Person(String firstName, String lastName)
        this.firstName = firstName;
        this.lastName = lastName;

    //Getters & Setters
    public String getFirstName() {
        return firstName;

    public void setFirstName(String firstName) {
        this.firstName = firstName;

    public String getLastName() {
        return lastName;

    public void setLastName(String lastName) {
        this.lastName = lastName;

Now that our person object is created we define a Person object and set the parameters in the BXML file. This is the information that will be passed in our Person object when we run the BXMLSerializer’s readObject method. That’s how the xml data creates the person object. At that point we can manipulate the Person object.



<Person></Person> Element
As you see above, this example defines an instance of a Person object. Notice this instance begins with a capital P for Person. The BXML Serializer will interpret this as an object instance. Remember to close the instance of the Person element using </Person>. If you don’t you end up with malformed XML that will generate the error

javax.xml.stream.XMLStreamException: ParseError at 
[row,col]:[6,1] Message: XML document structures must 
start and end within the same entity.

To fix this error, make sure you have the opening and closing element tags. In our example: <Person></Person>

The second line of the Person.bxml file defines the namespace of the xml. This is used for internal processing. Add this line of code to the root element of your bxml documents.

Also notice the second XML namespace that is defined. The XML namespace is denoted as xmlns=””. This tells the compiler where to find the definition of the class Person. In my example, the Person class is in a package called “logic”. Since the Person class is defined in logic.Person package, we only enter logic in the namespace. The class name is defined in the root element name <Person>. Pivot will combine the two to create the logic.Person object.

And lastly we set the attributes of the class – firstName and lastName. Pivot will automatically call the setters for these attributes. This is equivalent to:

//Instantiate a Person Object
Person myPersonObject = new Person();

//Set the First and Last Names using Setter Methods.

The Person.java class and the Person.bxml document are both completed. Now its time to build the Java program. The java program is created in two class files:
Driver.java – this is the entry point of all java programs including this one. This is where you load the Pivot application into a java program.
TestPerson.java – This class defines the User Interface and works with the BXML document (in our case: Person.bxml).


* This class represents the entry point into an
* Apache Pivot application on the desktop.

package demoApplication;

//Import the DesktopApplicationContext package.
import org.apache.pivot.wtk.DesktopApplicationContext;

public class Driver {

    //Entry point into all java applications.
    public static void main(String[] args) throws Exception
        * Load the pivot application into our Java program.
        * Remember to enter correct class in the parameter list..  
        DesktopApplicationContext.main(TestPerson.class, args);


In the driver class above, please note a few points:

  1. The org.apache.pivot.wtk.DesktopApplicationContext import is required in this class.
  2. The main method of the Desktop Application Context class is has two parameters:
    1. The first parameter is the class file that implements the Application interface. This is required.
    2. The second parameter is the list of arguments passed in via command line interface. This can be ignored if you are not using the command line to run your program.


* This class implements the Application interface which is
* the foundation for your Apache Pivot desktop programs.
* This is where you import your bxml files and build the
* program user interface.
package demoApplication;
* Import the person class. Notice how this matches up to the
* xmlns namespace in the Person.bxml document.
import logic.Person;
* The necessary Pivot imports that this class needs to run.
import org.apache.pivot.beans.BXMLSerializer;
import org.apache.pivot.collections.Map;
import org.apache.pivot.wtk.*; 

* This class must implement the Application Interface. This
* interface requires you to override four methods:
* startup
* shutdown
* suspend
* resume
public class TestPerson implements Application { 

    private Person person; //The person object for testing bxml serializer
    private Window window; //Currently not being used

    * The Application startup method is where to put your code for rendering UI.
    * The startup method requires the throws Exception to prevent an error
    * when trying to read to the bxml document. This handles the Serialization
    * Exception thrown if file not found.
    public void startup(Display display, Map<String, String> properties)
        throws Exception {

        //Create and instantiate a new BXML Serializer object.
        //This is used to read and process the bxml documents.
        BXMLSerializer bS = new BXMLSerializer(); 

        //Next, we call the read object method to read the bxml document.
        //Several things are happening here. 

        //First we get the Person.bxml resource which is retrieved using
        //getClass().getResource() method. The resource is the Person.bxml file 

        //Second, we read the xml data from the retrieved file. In this case
        //the BXML Serializer will cast our person object defined in the bxml
        //document into an object of type Object. 

        //Third we must cast the object that was returned from the BXML
        //Serializer into a Person object. That is accomplished using
        //casting. Casting is implemented with the (Person). And finally
        //we assign the newly created Person object into our variable called
        //"person". Now we can reference the attributes set in the bxml document.
        person = (Person) bS.readObject(getClass().getResource("Person.bxml"));

        //Print the First and Last Name.
        String name = person.getFirstName() + person.getLastName();
        System.out.println("Name is: " +  name);

    public boolean shutdown(boolean optional) {
        if (window != null) {
        return false;

    public void suspend() { } 

    @Override public void resume() { }

In the example above, the TestPerson class implements the Application interface which is required for the Apache Pivot application to run. The application interface defines four methods:

startup – This is the method you will use the most. Place all your code that runs as the application starts up here. For example, this is where the user interface for the GUI application is built.

shutdown – This is where you close the application.

resume and suspend – ignore for now.

There are at least three imports used in a basic Pivot application:

This containts the BXML Serializer used to retrieve and convert objects from the bxml documents.

This contains the Map class defined in the parameter list of the startup method.

This is the entire wtk package. This contains most of the UI elements you will use in your program.

In the startup method, I have created an instance of the BXMLSerializer object to retrieve the Person.bxml document. I cast the object that is return into a Person object and print the first and last name to the console. This program demonstrates how to build a desktop java application using the Apache Pivot framework. It also demonstrates how to create and access a class instance in the BXML document.

Categories: Apache Pivot
  1. No comments yet.
  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: