public class ActivityChooserModel extends DataSetObservable
This class represents a data model for choosing a component for handing a
given Intent
. The model is responsible for querying the system for
activities that can handle the given intent and order found activities
based on historical data of previous choices. The historical data is stored
in an application private file. If a client does not want to have persistent
choice history the file can be omitted, thus the activities will be ordered
based on historical usage for the current session.
For each backing history file there is a singleton instance of this class. Thus, several clients that specify the same history file will share the same model. Note that if multiple clients are sharing the same model they should implement semantically equivalent functionality since setting the model intent will change the found activities and they may be inconsistent with the functionality of some of the clients. For example, choosing a share activity can be implemented by a single backing model and two different views for performing the selection. If however, one of the views is used for sharing but the other for importing, for example, then each view should be backed by a separate model.
The way clients interact with this class is as follows:
// Get a model and set it to a couple of clients with semantically similar function.
ActivityChooserModel dataModel =
ActivityChooserModel.get(context, "task_specific_history_file_name.xml");
ActivityChooserModelClient modelClient1 = getActivityChooserModelClient1();
modelClient1.setActivityChooserModel(dataModel);
ActivityChooserModelClient modelClient2 = getActivityChooserModelClient2();
modelClient2.setActivityChooserModel(dataModel);
// Set an intent to choose a an activity for.
dataModel.setIntent(intent);
Note: This class is thread safe.
Modifier and Type | Class and Description |
---|---|
static interface |
ActivityChooserModel.ActivityChooserModelClient
Client that utilizes an
ActivityChooserModel . |
class |
ActivityChooserModel.ActivityResolveInfo
Represents an activity.
|
static interface |
ActivityChooserModel.ActivitySorter
Defines a sorter that is responsible for sorting the activities
based on the provided historical choices and an intent.
|
static class |
ActivityChooserModel.HistoricalRecord
Represents a record in the history.
|
static interface |
ActivityChooserModel.OnChooseActivityListener
Listener for choosing an activity.
|
Modifier and Type | Field and Description |
---|---|
static String |
DEFAULT_HISTORY_FILE_NAME
The default name of the choice history file.
|
static int |
DEFAULT_HISTORY_MAX_LENGTH
The default maximal length of the choice history.
|
mObservers
Modifier and Type | Method and Description |
---|---|
Intent |
chooseActivity(int index)
Chooses a activity to handle the current intent.
|
protected void |
finalize()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
|
static ActivityChooserModel |
get(Context context,
String historyFileName)
Gets the data model backed by the contents of the provided file with historical data.
|
ResolveInfo |
getActivity(int index)
Gets an activity at a given index.
|
int |
getActivityCount()
Gets the number of activities that can handle the intent.
|
int |
getActivityIndex(ResolveInfo activity)
Gets the index of a the given activity.
|
ResolveInfo |
getDefaultActivity()
Gets the default activity, The default activity is defined as the one
with highest rank i.e. the first one in the list of activities that can
handle the intent.
|
int |
getHistoryMaxSize()
Gets the history max size.
|
int |
getHistorySize()
Gets the history size.
|
Intent |
getIntent()
Gets the intent for which a activity is being chosen.
|
void |
setActivitySorter(ActivityChooserModel.ActivitySorter activitySorter)
Sets the sorter for ordering activities based on historical data and an intent.
|
void |
setDefaultActivity(int index)
Sets the default activity.
|
void |
setHistoryMaxSize(int historyMaxSize)
Sets the maximal size of the historical data.
|
void |
setIntent(Intent intent)
Sets an intent for which to choose a activity.
|
void |
setOnChooseActivityListener(ActivityChooserModel.OnChooseActivityListener listener)
Sets the listener for choosing an activity.
|
notifyChanged, notifyInvalidated
registerObserver, unregisterAll, unregisterObserver
public static final String DEFAULT_HISTORY_FILE_NAME
public static final int DEFAULT_HISTORY_MAX_LENGTH
public static ActivityChooserModel get(Context context, String historyFileName)
Note: To use the default historical data file clients should explicitly
pass as file name DEFAULT_HISTORY_FILE_NAME
. If no persistence of the choice
history is desired clients should pass null
for the file name. In such
case a new model is returned for each invocation.
Always use difference historical data files for semantically different actions. For example, sharing is different from importing.
context
- Context for loading resources.historyFileName
- File name with choice history, null
if the model should not be backed by a file. In this case the activities
will be ordered only by data from the current session.public void setIntent(Intent intent)
Note: Clients must set only semantically similar intents for each data model.
intent
- The intent.public Intent getIntent()
public int getActivityCount()
setIntent(Intent)
public ResolveInfo getActivity(int index)
ActivityChooserModel.ActivityResolveInfo
,
setIntent(Intent)
public int getActivityIndex(ResolveInfo activity)
activity
- The activity index.public Intent chooseActivity(int index)
Note: By calling this method the client guarantees that the returned intent will be started. This intent is returned to the client solely to let additional customization before the start.
Intent
for launching the activity or null if the
policy has consumed the intent or there is not current intent
set via setIntent(Intent)
.ActivityChooserModel.HistoricalRecord
,
ActivityChooserModel.OnChooseActivityListener
public void setOnChooseActivityListener(ActivityChooserModel.OnChooseActivityListener listener)
listener
- The listener.public ResolveInfo getDefaultActivity()
null
id not activities.getActivity(int)
public void setDefaultActivity(int index)
index
- The index of the activity to set as default.public void setActivitySorter(ActivityChooserModel.ActivitySorter activitySorter)
activitySorter
- The sorter.ActivityChooserModel.ActivitySorter
public void setHistoryMaxSize(int historyMaxSize)
DEFAULT_HISTORY_MAX_LENGTH
Note: Setting this property will immediately enforce the specified max history size by dropping enough old historical records to enforce the desired size. Thus, any records that exceed the history size will be discarded and irreversibly lost.
historyMaxSize
- The max history size.public int getHistoryMaxSize()
public int getHistorySize()
protected void finalize() throws Throwable
Object
finalize
method to dispose of
system resources or to perform other cleanup.
The general contract of finalize
is that it is invoked
if and when the JavaTM virtual
machine has determined that there is no longer any
means by which this object can be accessed by any thread that has
not yet died, except as a result of an action taken by the
finalization of some other object or class which is ready to be
finalized. The finalize
method may take any action, including
making this object available again to other threads; the usual purpose
of finalize
, however, is to perform cleanup actions before
the object is irrevocably discarded. For example, the finalize method
for an object that represents an input/output connection might perform
explicit I/O transactions to break the connection before the object is
permanently discarded.
The finalize
method of class Object
performs no
special action; it simply returns normally. Subclasses of
Object
may override this definition.
The Java programming language does not guarantee which thread will
invoke the finalize
method for any given object. It is
guaranteed, however, that the thread that invokes finalize will not
be holding any user-visible synchronization locks when finalize is
invoked. If an uncaught exception is thrown by the finalize method,
the exception is ignored and finalization of that object terminates.
After the finalize
method has been invoked for an object, no
further action is taken until the Java virtual machine has again
determined that there is no longer any means by which this object can
be accessed by any thread that has not yet died, including possible
actions by other objects or classes which are ready to be finalized,
at which point the object may be discarded.
The finalize
method is never invoked more than once by a Java
virtual machine for any given object.
Any exception thrown by the finalize
method causes
the finalization of this object to be halted, but is otherwise
ignored.