net.zer0bandwidth.android.lib.services

Class SimpleServiceConnection<S extends android.app.Service>

java.lang.Object

net.zer0bandwidth.android.lib.services.SimpleServiceConnection<S>

All Implemented Interfaces:

android.content.ServiceConnection

public class SimpleServiceConnection<S extends android.app.Service>
extends java.lang.Object
implements android.content.ServiceConnection

This class provides a simple, consistent implementation of a service binding, so that neither the service nor the consumer of that service is required to have its own implementation. The class provides basic methods to bind to, and unbind from, the service; get the bound instance of the service; bind as a listener to the connection itself. Note: In version 0.1.0 (#19), the class's members and inner classes were fundamentally modified to provide tighter access to the connected service class. While this makes the class more convenient to use, it is a flag day beyond which consumers of this class will need to be modified to catch up.

Since:

zer0bandwidth-net/android 0.0.1 (#1)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	SimpleServiceConnection.InstanceBinder<BS extends android.app.Service> The binder provided by the service needs to implement this interface, which provides us with a standard way to reach into the service's own public methods.
static interface	SimpleServiceConnection.Listener<LS extends android.app.Service> Because connections can take a while, the object that is waiting for the connection to be completed should implement this interface to receive a signal when the connection is established.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_BINDING_FLAGS By default, the connection will bind at a level above the consumer, and auto-create the service if it has not yet been started.
protected boolean	m_bBound Indicates whether the connection is, indeed, bound to a service.
protected java.lang.Class<S>	m_clsService Stores a consistent hint to the service class to which this connection will bind.
protected S	m_srvInstance The bound instance.
protected java.util.Vector<SimpleServiceConnection.Listener<S>>	m_vListeners A collection of objects listening to this connection.

Constructor Summary

Constructors

Constructor and Description
SimpleServiceConnection(java.lang.Class<S> cls) Initializes a simple connection for a specified service class.

Method Summary

Modifier and Type	Method and Description
SimpleServiceConnection<S>	addListener(SimpleServiceConnection.Listener<S> l) Registers a listener to this collection, if it is not already listening.
SimpleServiceConnection<S>	connect(android.content.Context ctx) Attempts to connect to the service, using the default binding control flags.
SimpleServiceConnection<S>	connect(android.content.Context ctx, int bmFlags) Attempts to connect to the service.
SimpleServiceConnection<S>	disconnect(android.content.Context ctx) Attempts to break the connection to the service.
protected java.util.Vector<SimpleServiceConnection.Listener<S>>	getListeners() Accesses the pool of listeners, verifying first that such a pool has been initialized.
protected java.lang.String	getLogTag() For log messages generated by methods of this class, or any descendant class, use this method, which examines the class of the instance from which it is called, and returns that class's simple name.
java.lang.Class<S>	getServiceClass() Accessor for the service class hint.
S	getServiceInstance() Accessor for the service instance, if the connection is bound.
protected SimpleServiceConnection<S>	initListeners() Initializes the pool of connection listeners.
boolean	isBound() Indicates whether the connection is bound.
boolean	isConnected() Perhaps more useful than isBound(), this function verifies not only that the connection is bound, but also that the persistent reference to the service is not null.
<C extends android.app.Service> boolean	isServiceClass(java.lang.Class<C> cls) Indicates whether the connection is indeed bound to an instance of the specified class.
void	onServiceConnected(android.content.ComponentName cn, android.os.IBinder binder) Called by the Android OS when a the service accepts the connection's binding.
void	onServiceDisconnected(android.content.ComponentName cn) Called by the Android OS when a connection's binding to the service must be broken.
SimpleServiceConnection<S>	removeListener(SimpleServiceConnection.Listener<S> l) Unregisters a listener to this collection, if it is found in the pool.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface android.content.ServiceConnection

onBindingDied

Field Detail

DEFAULT_BINDING_FLAGS

public static final int DEFAULT_BINDING_FLAGS

By default, the connection will bind at a level above the consumer, and auto-create the service if it has not yet been started. Used by the class's connect(android.content.Context, int) methods in absence of any flag set specified by the caller.

See Also:

Constant Field Values

m_clsService

protected java.lang.Class<S extends android.app.Service> m_clsService

Stores a consistent hint to the service class to which this connection will bind.

m_srvInstance

protected S extends android.app.Service m_srvInstance

The bound instance.

m_bBound

protected boolean m_bBound

Indicates whether the connection is, indeed, bound to a service.

m_vListeners

protected java.util.Vector<SimpleServiceConnection.Listener<S extends android.app.Service>> m_vListeners

A collection of objects listening to this connection.

Constructor Detail

SimpleServiceConnection

public SimpleServiceConnection(java.lang.Class<S> cls)

Initializes a simple connection for a specified service class.

Parameters:

cls - the service class

Method Detail

getLogTag

protected final java.lang.String getLogTag()

For log messages generated by methods of this class, or any descendant class, use this method, which examines the class of the instance from which it is called, and returns that class's simple name. This allows other projects to extend this class without having to override this method.

Returns:

a logging tag for this connection object

initListeners

protected SimpleServiceConnection<S> initListeners()

Initializes the pool of connection listeners.

Returns:

the connection, for fluid invocations

getListeners

protected java.util.Vector<SimpleServiceConnection.Listener<S>> getListeners()

Accesses the pool of listeners, verifying first that such a pool has been initialized.

Returns:

a collection of listeners to this connection

addListener

public SimpleServiceConnection<S> addListener(SimpleServiceConnection.Listener<S> l)

Registers a listener to this collection, if it is not already listening.

Parameters:

l - the listener to be added

Returns:

the connection, for fluid invocations

removeListener

public SimpleServiceConnection<S> removeListener(SimpleServiceConnection.Listener<S> l)

Unregisters a listener to this collection, if it is found in the pool.

Parameters:

l - the listener to be removed

Returns:

the connection, for fluid invocations

getServiceClass

public java.lang.Class<S> getServiceClass()

Accessor for the service class hint.

Returns:

the service class hint

isServiceClass

public <C extends android.app.Service> boolean isServiceClass(java.lang.Class<C> cls)

Indicates whether the connection is indeed bound to an instance of the specified class.

Parameters:

cls - the class to which we should compare our bound service

Returns:

true iff the specified class is the bound service's class

isBound

public boolean isBound()

Indicates whether the connection is bound.

Returns:

an indication that the service is bound

isConnected

public boolean isConnected()

Perhaps more useful than isBound(), this function verifies not only that the connection is bound, but also that the persistent reference to the service is not null.

Returns:

an indication that the connection is, indeed, connected

Since:

zer0bandwidth-net/android 0.0.1 (#5)

getServiceInstance

public S getServiceInstance()

Accessor for the service instance, if the connection is bound.

Returns:

the bound instance of the service, if any

connect

public SimpleServiceConnection<S> connect(android.content.Context ctx,
                                          int bmFlags)
                                   throws java.lang.IllegalArgumentException

Attempts to connect to the service. The caller should not process the return value of this method immediately in order to access the service; rather, it should handle the consequences of the connection by implementing SimpleServiceConnection.Listener.onServiceConnected(net.zer0bandwidth.android.lib.services.SimpleServiceConnection<LS>).

Parameters:

ctx - the context in which to bind to the service

bmFlags - a mask of optional binding flags; see Context

Returns:

the connection, for fluid invocations

Throws:

java.lang.IllegalArgumentException - if the context is null

connect

public SimpleServiceConnection<S> connect(android.content.Context ctx)

Attempts to connect to the service, using the default binding control flags. The caller should not process the return value of this method immediately in order to access the service; rather, it should handle the consequences of the connection by implementing SimpleServiceConnection.Listener.onServiceConnected(net.zer0bandwidth.android.lib.services.SimpleServiceConnection<LS>).

Parameters:

ctx - the context in which to bind to the service

Returns:

the connection, for fluid invocations

See Also:

DEFAULT_BINDING_FLAGS

disconnect

public SimpleServiceConnection<S> disconnect(android.content.Context ctx)

Attempts to break the connection to the service. Methods that tear down the context in which the service was started (such as Activity.onStop()) should call this method to free the service binding. The caller should not assume that the binding was successfully released; any other consequences of releasing this binding should be handled by implementing SimpleServiceConnection.Listener.onServiceDisconnected(net.zer0bandwidth.android.lib.services.SimpleServiceConnection<LS>).

Parameters:

ctx - the context in which the binding should be broken

Returns:

the connection, for fluid invocations

onServiceConnected

public void onServiceConnected(android.content.ComponentName cn,
                               android.os.IBinder binder)

Called by the Android OS when a the service accepts the connection's binding. Notifies all of the connection's listeners that the binding has been completed.

Specified by:

onServiceConnected in interface android.content.ServiceConnection

Parameters:

cn - the name of the service component

binder - a binder to the service

onServiceDisconnected

public void onServiceDisconnected(android.content.ComponentName cn)

Called by the Android OS when a connection's binding to the service must be broken. Notifies all of the connection's listeners that the binding has been broken.

Specified by:

onServiceDisconnected in interface android.content.ServiceConnection

Parameters:

cn - the name of the service component