Bundles of Primitive and Reference Types

A VaporBundle is a fluent version of the standard Android Bundle, with the addition of support for storing arbitrary reference types.

Furthermore, a VaporBundle has been designed to provide jQuery flavored simplicity and method chaining to aid developers with passing data around your Android app.

Below is just an overview of how to use a VaporBundle in your code, see the documentation for full details.

Reference Type Support

In general the standard Android Bundle does not support storing of arbitrary reference types, which is understandable given its primary role as a vessel for primitive data between parts of an Android app.

In the Vapor Android framework however there are cases where you will want to also store your own objects in a bundle along with this primitive data, and as such there is support for object storage built-in to a VaporBundle.

For example, when defining an Animation you pass your settings in a VaporBundle. Conveniently, inside this VaporBundle you can also put the animation listener object:

    $.ImageView(R.id.image1).pulse(
        // pass the animation settings in a VaporBundle
        $.Bundle()
            .put("repeat", 5) // pulse 5 times
            .put("animListener", 
                
                new $anim() {

                    @Override
		                public void onAnimationStart(Animator animation) {
			                ...
		                }
                }

            ) // we can store the $anim listener in the settings too!
    );

The Vapor Android framework stores arbitrary reference types in the VaporBundle object only, they will not be found in the underlying Android Bundle (which can be retrieved using .bundle())

Creating A VaporBundle

As with the majority of the Vapor Android framework you should do your VaporBundle creation through the relevant $ helper methods.

At present the Vapor Android framework supports creating a VaporBundle in two ways, firstly you can just use an empty constructor:

    VaporBundle vb = $.Bundle();

This will return you a fresh VaporBundle without any data mapped inside it. However, if you already have an existing Android Bundle with data in it you can also use this to create a VaporBundle:

    Bundle bundle; // existing Android Bundle
    ...

    VaporBundle vb = $.Bundle(bundle);

The existing data from the Android Bundle is now held inside the new VaporBundle instance, allowing you to continue working with it.

Storing Data

Like Vapor Intent and Vapor Shared Preferences, you store data in a VaporBundle using the overloaded .put(...) method.

The benefit of this is that you needn't worry about the actual type of the value being stored, the correct method for handling that data type is resolved for you thanks to Java's support for overloading!

Moreover, being fluent means you can chain .put(...) calls together, like in jQuery, allowing developers to store a load of data at once.

For example here we need to pass a VaporBundle as a parameter so we just create it in place:

    someMethod(

	    $.Bundle()
            .put("key1", true)
            .put("key2", 245)
            .put("key3", "Hello World!") // Bundle created and populated!
    );

Retrieving Data

App developers need to be a bit more specific with the methods we call to retrieve data.

The convention for method names here is .get___(String) where you fill in the blank with a the name of datatype being retrieved:

    VaporBundle vb = $.Bundle().put("myInt", 123);
    ...

    vb.getInt("myInt"); // retrieve the int mapped to "myInt"

And that's all there is to it! Using Vapor Bundles in your Android application is really that simple, and they are a great general purpose structure in Vapor for passing custom data around.