com.sawyer.advadapters.widget

Class JSONAdapter

java.lang.Object

android.widget.BaseAdapter

com.sawyer.advadapters.widget.JSONAdapter

All Implemented Interfaces:

Adapter, Filterable, ListAdapter, SpinnerAdapter

public abstract class JSONAdapter
extends BaseAdapter
implements Filterable

A custom abstract BaseAdapter that is backed by a JSONArray of arbitrary objects. By default this class delegates view generation and defining the filtering logic to subclasses.

Designed to be a flexible and customizable solution for using JSONArray with an adapter. It exposes most of the JSONArray methods, provides active filtering support, and conveniently passes along a layout inflater for view creation. Keep in mind JSONArray itself has limited capabilities which restricts what this adapter can do.

Because of the background filtering process, all methods which mutates the underlying data are internally synchronized. This ensures a thread safe environment for internal write operations. If filtering is not required, it's strongly recommended to use the NFJSONArrayAdapter instead. In order to support the multitude of data types a JSONArray can store, the filtering mechanism is built to be very robust.

Only the isFilteredOut(Object, CharSequence) is required to be implemented by subclasses. Pre-built methods for handing the logic for Boolean, Double, Integer, Long, and String already exist. You may override them to provide an alternate behavior. In addition, you can provide your own filtered methods for custom data types. During adapter construction, any methods which match the isFilteredOut method signature are cached. Then during a filter operation, will be invoked via reflection when required.

For example, lets say you created your own object type called Foo. You've stored several instances of Foo within the adapter along with JSONObjects, Integers, and Booleans. In order to specifically support a isFilteredOut method for your Foo object, have your subclass implement a isFilteredOut(Foo, CharSequence). Then during a filter operation, any Foo object detected will have that method invoke to determine whether it passes the filter or not.

Field Summary

Fields inherited from interface android.widget.Adapter

IGNORE_ITEM_VIEW_TYPE, NO_SELECTION

Constructor Summary

Constructors

Constructor and Description
JSONAdapter(Context activity) Constructor
JSONAdapter(Context activity, Collection items) Constructor
JSONAdapter(Context activity, JSONArray array)
JSONAdapter(Context activity, JSONTokener readFrom) Constructor
JSONAdapter(Context activity, String json) * Constructor

Method Summary

Modifier and Type	Method and Description
void	add(boolean item) Adds the specified items at the end of the adapter.
void	add(double item) Adds the specified items at the end of the adapter.
void	add(int item) Adds the specified items at the end of the adapter.
void	add(long item) Adds the specified items at the end of the adapter.
void	add(Object item) Adds the specified items at the end of the adapter.
void	addAll(JSONArray items) Adds the specified JSONArray at the end of the adapter.
void	addAll(Object... items) Adds the specified items at the end of the adapter.
void	clear() Remove all elements from the adapter.
Context	getContext()
int	getCount()
View	getDropDownView(int position, View convertView, ViewGroup parent)
View	getDropDownView(LayoutInflater inflater, int position, View convertView, ViewGroup parent) Get a View that displays in the drop down popup the data at the specified position in the data set.
Filter	getFilter()
JSONArray	getFilteredJSONArray()
Object	getItem(int position)
boolean	getItemBoolean(int position) Gets the boolean data item associated with the specified position in the data set.
double	getItemDouble(int position) Gets the double data item associated with the specified position in the data set.
long	getItemId(int position)
int	getItemInt(int position) Gets the int data item associated with the specified position in the data set.
JSONArray	getItemJSONArray(int position) Gets the JSONArray data item associated with the specified position in the data set.
JSONObject	getItemJSONObject(int position) Gets the JSONObject data item associated with the specified position in the data set.
long	getItemLong(int position) Gets the long data item associated with the specified position in the data set.
String	getItemString(int position) Gets the String data item associated with the specified position in the data set.
JSONArray	getJSONArray()
View	getView(int position, View convertView, ViewGroup parent)
abstract View	getView(LayoutInflater inflater, int position, View convertView, ViewGroup parent) Get a View that displays the data at the specified position in the data set.
boolean	isNull(int position)
void	notifyDataSetChanged()
Object	optItem(int position) Gets the data item associated with the specified position in the adapter or null if there is no value at position.
boolean	optItemBoolean(int position) Gets the boolean data item associated with the specified position in the adapter or null if there is no value at position.
boolean	optItemBoolean(int position, boolean fallback) Gets the boolean data item associated with the specified position in the adapter or null if there is no value at position.
double	optItemDouble(int position) Gets the double data item associated with the specified position in the adapter or null if there is no value at position.
double	optItemDouble(int position, double fallback) Gets the double data item associated with the specified position in the adapter or null if there is no value at position.
int	optItemInt(int position) Gets the int data item associated with the specified position in the adapter or null if there is no value at position.
int	optItemInt(int position, int fallback) Gets the int data item associated with the specified position in the adapter or null if there is no value at position.
JSONArray	optItemJSONArray(int position) Gets the JSONArray data item associated with the specified position in the adapter or null if there is no value at position.
JSONObject	optItemJSONObject(int position) Gets the JSONObject data item associated with the specified position in the adapter or null if there is no value at position.
long	optItemLong(int position) Gets the long data item associated with the specified position in the adapter or null if there is no value at position.
long	optItemLong(int position, long fallback) Gets the long data item associated with the specified position in the adapter or null if there is no value at position.
String	optItemString(int position) Gets the String data item associated with the specified position in the adapter or null if there is no value at position.
String	optItemString(int position, String fallback) Gets the String data item associated with the specified position in the adapter or null if there is no value at position.
void	setJSONArray(JSONArray items) Resets the adapter to store a new JSONArray of items.
void	setNotifyOnChange(boolean notifyOnChange) Control whether methods that change the list (add(java.lang.Object), clear()) automatically call notifyDataSetChanged().

Methods inherited from class android.widget.BaseAdapter

areAllItemsEnabled, getItemViewType, getViewTypeCount, hasStableIds, isEmpty, isEnabled, notifyDataSetInvalidated, registerDataSetObserver, unregisterDataSetObserver

Methods inherited from class java.lang.Object

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

Constructor Detail

JSONAdapter

public JSONAdapter(Context activity)

Constructor

Parameters:

activity - Context used for inflating views

JSONAdapter

public JSONAdapter(Context activity,
                   JSONTokener readFrom)
            throws JSONException

Constructor

Parameters:

activity - Context used for inflating views

readFrom - a tokener whose nextValue() method will yield a JSONArray to be stored in the adapter.

Throws:

JSONException - if the parse fails or doesn't yield a JSONArray.

JSONAdapter

public JSONAdapter(Context activity,
                   String json)
            throws JSONException

* Constructor

Parameters:

activity - Context used for inflating views

json - a JSON-encoded string containing an array to be stored in the adapter

Throws:

JSONException - if the parse fails or doesn't yield a JSONArray.

JSONAdapter

public JSONAdapter(Context activity,
                   JSONArray array)

JSONAdapter

public JSONAdapter(Context activity,
                   Collection items)

Constructor

Parameters:

activity - Context used for inflating views

items - The items to represent within the adapter.

Method Detail

add

public void add(Object item)

Adds the specified items at the end of the adapter. May not be NaNs or infinities which will cause the adapter to be in an inconsistent state. Will repeat the last filtering request if invoked while filtered results are being displayed.

Parameters:

item - The item to add at the end of the adapter.

add

public void add(double item)
         throws JSONException

Adds the specified items at the end of the adapter. May not be NaNs or infinities. Will repeat the last filtering request if invoked while filtered results are being displayed.

Parameters:

item - The item to add at the end of the adapter.

Throws:

JSONException - If item is NaN or infinity

add

public void add(long item)

Adds the specified items at the end of the adapter. Will repeat the last filtering request if invoked while filtered results are being displayed.

Parameters:

item - The item to add at the end of the adapter.

add

public void add(boolean item)

Adds the specified items at the end of the adapter. Will repeat the last filtering request if invoked while filtered results are being displayed.

Parameters:

item - The item to add at the end of the adapter.

add

public void add(int item)

Adds the specified items at the end of the adapter. Will repeat the last filtering request if invoked while filtered results are being displayed.

Parameters:

item - The item to add at the end of the adapter.

addAll

public void addAll(JSONArray items)

Adds the specified JSONArray at the end of the adapter. May not contain NaNs or infinities which will cause the adapter to be in an inconsistent state. Will repeat the last filtering request if invoked while filtered results are being displayed.

Parameters:

items - The JSONArray to add at the end of the adapter.

addAll

public void addAll(Object... items)

Adds the specified items at the end of the adapter. May not contain NaNs or infinities which will cause the adapter to be in an inconsistent state. Will repeat the last filtering request if invoked while filtered results are being displayed.

Parameters:

items - The items to add at the end of the adapter.

clear

public void clear()

Remove all elements from the adapter.

getContext

public Context getContext()

Returns:

The Context associated with this adapter.

getCount

public int getCount()

Specified by:

getCount in interface Adapter

getDropDownView

public View getDropDownView(LayoutInflater inflater,
                            int position,
                            View convertView,
                            ViewGroup parent)

Get a View that displays in the drop down popup the data at the specified position in the data set.

Parameters:

inflater - the LayoutInflater object that can be used to inflate each view.

position - index of the item whose view we want.

convertView - the old view to reuse, if possible. Note: You should check that this view is non-null and of an appropriate type before using. If it is not possible to convert this view to display the correct data, this method can create a new view.

parent - the parent that this view will eventually be attached to

Returns:

a View corresponding to the data at the specified position.

getDropDownView

public final View getDropDownView(int position,
                                  View convertView,
                                  ViewGroup parent)

Specified by:

getDropDownView in interface SpinnerAdapter

Overrides:

getDropDownView in class BaseAdapter

getFilter

public Filter getFilter()

Specified by:

getFilter in interface Filterable

getFilteredJSONArray

public JSONArray getFilteredJSONArray()

Returns:

The shown filtered JSONArray. If no filter is applied, then the original JSONArray is returned.

getItem

public Object getItem(int position)

Specified by:

getItem in interface Adapter

getItemBoolean

public boolean getItemBoolean(int position)
                       throws JSONException

Gets the boolean data item associated with the specified position in the data set.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

Returns:

The data at the specified position as a boolean.

Throws:

JSONException - If the value at position doesn't exit or cannot be coerced to a boolean.

getItemDouble

public double getItemDouble(int position)
                     throws JSONException

Gets the double data item associated with the specified position in the data set.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

Returns:

The data at the specified position as a double.

Throws:

JSONException - If the value at position doesn't exit or cannot be coerced to a double.

getItemId

public long getItemId(int position)

Specified by:

getItemId in interface Adapter

getItemInt

public int getItemInt(int position)
               throws JSONException

Gets the int data item associated with the specified position in the data set.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

Returns:

The data at the specified position as a int.

Throws:

JSONException - If the value at position doesn't exit or cannot be coerced to a int.

getItemJSONArray

public JSONArray getItemJSONArray(int position)
                           throws JSONException

Gets the JSONArray data item associated with the specified position in the data set.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

Returns:

The data at the specified position as a JSONArray.

Throws:

JSONException - If the value at position doesn't exit or is not a JSONArray.

getItemJSONObject

public JSONObject getItemJSONObject(int position)
                             throws JSONException

Gets the JSONObject data item associated with the specified position in the data set.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

Returns:

The data at the specified position as a JSONObject.

Throws:

JSONException - If the value at position doesn't exit or is not a JSONObject.

getItemLong

public long getItemLong(int position)
                 throws JSONException

Gets the long data item associated with the specified position in the data set.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

Returns:

The data at the specified position as a long.

Throws:

JSONException - If the value at position doesn't exit or cannot be coerced to a long.

getItemString

public String getItemString(int position)
                     throws JSONException

Gets the String data item associated with the specified position in the data set.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

Returns:

The data at the specified position as a String.

Throws:

JSONException - If no such value exists.

getJSONArray

public JSONArray getJSONArray()

Returns:

The original (unfiltered) list of items stored within the Adapter

setJSONArray

public void setJSONArray(JSONArray items)

Resets the adapter to store a new JSONArray of items. Convenient way of calling clear(), then addAll(org.json.JSONArray) without having to worry about an extra notifyDataSetChanged() invoked in between. Will repeat the last filtering request if invoked while filtered results are being displayed.

Parameters:

items - New JSONArray of items to store within the adapter.

getView

public abstract View getView(LayoutInflater inflater,
                             int position,
                             View convertView,
                             ViewGroup parent)

Get a View that displays the data at the specified position in the data set. You can either create a View manually or inflate it from an XML layout file. When the View is inflated, the parent View (GridView, ListView...) will apply default layout parameters unless you use LayoutInflater.inflate(int, android.view.ViewGroup, boolean) to specify a root view and to prevent attachment to the root.

Parameters:

inflater - the LayoutInflater object that can be used to inflate each view.

position - The position of the item within the adapter's data set of the item whose view we want.

convertView - The old view to reuse, if possible. Note: You should check that this view is non-null and of an appropriate type before using. If it is not possible to convert this view to display the correct data, this method can create a new view. Heterogeneous lists can specify their number of view types, so that this View is always of the right type (see BaseAdapter.getViewTypeCount() and BaseAdapter.getItemViewType(int)).

parent - The parent that this view will eventually be attached to

Returns:

A View corresponding to the data at the specified position.

getView

public final View getView(int position,
                          View convertView,
                          ViewGroup parent)

Specified by:

getView in interface Adapter

isNull

public boolean isNull(int position)

Returns:

True if this adapter has no value at position, or if it's value is the null reference or NULL.

notifyDataSetChanged

public void notifyDataSetChanged()

Overrides:

notifyDataSetChanged in class BaseAdapter

optItem

public Object optItem(int position)

Gets the data item associated with the specified position in the adapter or null if there is no value at position.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

Returns:

The data at the specified position or null.

optItemBoolean

public boolean optItemBoolean(int position)

Gets the boolean data item associated with the specified position in the adapter or null if there is no value at position.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

Returns:

The boolean data at the specified position or null.

optItemBoolean

public boolean optItemBoolean(int position,
                              boolean fallback)

Gets the boolean data item associated with the specified position in the adapter or null if there is no value at position.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

fallback - Value to return if no data is found.

Returns:

The boolean data at the specified position or otherwise the fallback.

optItemDouble

public double optItemDouble(int position)

Gets the double data item associated with the specified position in the adapter or null if there is no value at position.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

Returns:

The double data at the specified position or null.

optItemDouble

public double optItemDouble(int position,
                            double fallback)

Gets the double data item associated with the specified position in the adapter or null if there is no value at position.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

fallback - Value to return if no data is found.

Returns:

The double data at the specified position or otherwise the fallback.

optItemInt

public int optItemInt(int position)

Gets the int data item associated with the specified position in the adapter or null if there is no value at position.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

Returns:

The int data at the specified position or null.

optItemInt

public int optItemInt(int position,
                      int fallback)

Gets the int data item associated with the specified position in the adapter or null if there is no value at position.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

fallback - Value to return if no data is found.

Returns:

The int data at the specified position or otherwise the fallback.

optItemJSONArray

public JSONArray optItemJSONArray(int position)

Gets the JSONArray data item associated with the specified position in the adapter or null if there is no value at position.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

Returns:

The JSONArray data at the specified position or null.

optItemJSONObject

public JSONObject optItemJSONObject(int position)

Gets the JSONObject data item associated with the specified position in the adapter or null if there is no value at position.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

Returns:

The JSONObject data at the specified position or null.

optItemLong

public long optItemLong(int position)

Gets the long data item associated with the specified position in the adapter or null if there is no value at position.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

Returns:

The long data at the specified position or null.

optItemLong

public long optItemLong(int position,
                        long fallback)

Gets the long data item associated with the specified position in the adapter or null if there is no value at position.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

fallback - Value to return if no data is found.

Returns:

The long data at the specified position or otherwise the fallback.

optItemString

public String optItemString(int position)

Gets the String data item associated with the specified position in the adapter or null if there is no value at position.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

Returns:

The String data at the specified position or null.

optItemString

public String optItemString(int position,
                            String fallback)

Gets the String data item associated with the specified position in the adapter or null if there is no value at position.

Parameters:

position - Position of the item whose data we want within the adapter's data set.

fallback - Value to return if no data is found.

Returns:

The String data at the specified position or otherwise the fallback.

setNotifyOnChange

public void setNotifyOnChange(boolean notifyOnChange)

Control whether methods that change the list (add(java.lang.Object), clear()) automatically call notifyDataSetChanged(). If set to false, caller must manually call notifyDataSetChanged() to have the changes reflected in the attached view.

The default is true, and calling notifyDataSetChanged() resets the flag to true.

Parameters:

notifyOnChange - if true, modifications to the list will automatically call notifyDataSetChanged()