A Framework For Easy Service Bindings

Another goal of the Vapor Android framework is to take the confusion out of binding to, and management of Services in clients.

A client in this sense is either derived from VaporActivity or VaporService, both of which implement VaporServiceBindable.

Below is an overview of the methods found in this interface.

App developers should use .vsc(Class<? extends Service> serviceClass) to generate service connections, as this plays a crucial role in implicit management of service bindings

Binding To A Service

vsc(Class<? extends Service>)

Developers should use this method to generate a VaporServiceConnection from the client to the Service represented by the given Class.

The VaporServiceConnection will store itself inside the client so that the connection can be easily managed using the methods described below.

It will also trigger hooks at appropriate times that inform hookees (observers) when a client has bound to, or unbound from, a service.

bindService(Intent, ServiceConnection, int)

This method is both an override of the method from Activity, as well as part of the VaporServiceBindable interface.

In most cases Android app developers needn't invoke this method directly, instead you should bind to services through the $.bind(...) family of methods, which take care of creating the binding for you implicitly.

Managing A Binding

service(Class<T extends Service>)

The Vapor Android framework provides a convenient way of retrieving the Service instance the client is mapped to, making it easy to invoke Service methods in the following way:

	$.bind(MyService.class,this); // bind this client to MyService service
	...

    // invoke someMethod() defined in bound MyService instance
	this.service(MyService.class).someMethod(); 

Like much of the Vapor Android framework, the service(Class<T extends Service>) method utilises generics so that app developers don't have to cast the return type

binding(Class<T extends Service>)

This method returns the actual instance of VaporServiceConnection that was used to create the Service binding.

Android app developers will find this useful when they wish to probe additional information about the service binding, as opposed to the Service itself.

unbindService(Class<? extends Service>)

This is undoubtedly one of the coolest parts of the VaporServiceBindable interface. The Vapor framework lets you unbind from a Service just by providing its class, unlike Android which requires the ServiceConnection instance!

The Vapor framework will do the work in providing the relevant ServiceConnection instance for you behind-the-scenes!

Vapor will unbind all services the client has bound to automatically when the client is being destroyed

unbindService(ServiceConnection)

This method is both an override of the method from Activity, as well as part of the VaporServiceBindable interface.

In most cases Android app developers needn't invoke this method directly, instead you should unbind from services through the $.unbind(...) family of methods, which take care of the unbinding for you implicitly.

Alternatively, use unbindService(Class<? extends Service> serviceClass) in the client, the Vapor Android framework will handle the rest!

unbindServices()

At any time app developers can call this method to unbind from all services to which your client is currently connected!

Accordingly, VaporActivities and VaporServices will do this automatically when they are being destroyed by the OS.

This means you needn't worry about service leaks from bindings that last for the lifetime of your VaporServiceBindable instance!