com.twofortyfouram.locale.sdk.host.model

Class PluginConfiguration

java.lang.Object

com.twofortyfouram.locale.sdk.host.model.PluginConfiguration

All Implemented Interfaces:

Parcelable

@Immutable
public final class PluginConfiguration
extends Object
implements Parcelable

Contains dynamic configuration for a plug-in.

Nested Class Summary

Nested classes/interfaces inherited from interface android.os.Parcelable

Parcelable.ClassLoaderCreator<T>, Parcelable.Creator<T>

Field Summary

Fields

Modifier and Type	Field and Description
static Parcelable.Creator<PluginConfiguration>	CREATOR Implements the Parcelable interface

Fields inherited from interface android.os.Parcelable

CONTENTS_FILE_DESCRIPTOR, PARCELABLE_WRITE_RETURN_VALUE

Constructor Summary

Constructors

Constructor and Description
PluginConfiguration(boolean isBackwardsCompatibilityEnabled, boolean isRequiresConnectivity, boolean isDisruptsConnectivity, boolean isBuggy, boolean isDrainsBattery, boolean isBlacklisted, Collection<String> alternatives) Constructs a new plug-in configuration.

Method Summary

Modifier and Type	Method and Description
int	describeContents()
boolean	equals(Object o)
Collection<String>	getAlternatives() Determines whether a third party plug-in has an alternative first party implementation.
int	hashCode()
boolean	isBackwardsCompatibilityEnabled() Determines whether the plug-in requires backwards compatibility.
boolean	isBlacklisted() Determines whether a plug-in is blacklisted.
boolean	isBuggy() Determines whether a plug-in is known to be buggy.
boolean	isDisruptsConnectivity()
boolean	isDrainsBattery() Determines whether a plug-in has an extreme impact on battery life.
boolean	isRequiresConnectivity()
void	writeToParcel(Parcel dest, int flags)

Methods inherited from class java.lang.Object

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

Field Detail

CREATOR

public static final Parcelable.Creator<PluginConfiguration> CREATOR

Implements the Parcelable interface

Constructor Detail

PluginConfiguration

public PluginConfiguration(boolean isBackwardsCompatibilityEnabled,
                           boolean isRequiresConnectivity,
                           boolean isDisruptsConnectivity,
                           boolean isBuggy,
                           boolean isDrainsBattery,
                           boolean isBlacklisted,
                           Collection<String> alternatives)

Constructs a new plug-in configuration.

Parameters:

isBackwardsCompatibilityEnabled - If backwards compatibility for pre-1.0 plug-in API is enabled.

isRequiresConnectivity - If the plug-in requires Internet connectivity.

isDisruptsConnectivity - If the plug-in disrupts Internet connectivity.

isBuggy - If the plug-in is known to be buggy.

isDrainsBattery - If the plug-in is known to drain the battery.

isBlacklisted - If the plug-in is to be disabled.

alternatives - Alternatives to the plug-in, as a collection of registry names.

Method Detail

isBackwardsCompatibilityEnabled

public boolean isBackwardsCompatibilityEnabled()

Determines whether the plug-in requires backwards compatibility.

The beta version of the plug-in API for Locale released in January 2009 was slightly different from the final version of the API released in December 2009. Prior to Locale 1.0, Intent.EXTRA_BUNDLE didn't exist and plug-ins stored and retrieved their extras directly from the Intent.ACTION_EDIT_SETTING or Intent.ACTION_FIRE_SETTING Intents. Although this backwards compatibility should only apply to Setting plug-ins (since Conditions weren't supported until the API was finalized in Locale 1.0), some plug-in developers copy-pasted their setting implementations to create conditions so some conditions need backwards compatibility enabled as well.

Returns:

true if backwards compatibility is enabled for the plug-in.

isRequiresConnectivity

public boolean isRequiresConnectivity()

isDisruptsConnectivity

public boolean isDisruptsConnectivity()

Returns:

true if the plug-in disrupts Internet connectivity.

isBuggy

public boolean isBuggy()

Determines whether a plug-in is known to be buggy. The UI might use this to warn the user about the plug-in. Such a warning improves the user experience, as the user won't wonder whether they've set things up correctly when a plug-in doesn't work.

A buggy plug-in is different from a blacklisted plug-in, as a buggy plug-in may still provide some working functionality to the user. An example of a buggy plug-in would be a third party location condition plug-in that doesn't implement proper hysteresis. Such a plug-in may work, but the user would perceive the plug-in as not behaving well.

Returns:

true if the plug-in is known to be buggy.

isDrainsBattery

public boolean isDrainsBattery()

Determines whether a plug-in has an extreme impact on battery life. The UI might use this information to display a warning to the user, in order to prevent users from blaming the host app for battery drain caused by a plug-in.

Returns:

true if the plug-in is known to drain the battery.

isBlacklisted

public boolean isBlacklisted()

Determines whether a plug-in is blacklisted. A blacklisted plug-in is not considered a valid plug-in by the host and will be ignored by the host.

While preserving user choice is always important, some plug-ins are so malicious, buggy, otherwise problematic that they must be disabled in order to protect the interests of users. Before anyone panics, it should be noted that plug-ins are only blacklisted under exceptional circumstances. This API is maintained so that the entire ecosystem can quickly be protected if absolutely necessary. The decision whether to blacklist a plug-in is fully at the discretion of two forty four a.m. LLC, although the following guidelines cover the blacklisting process. two forty four a.m. LLC's ability to blacklist does not imply that two forty four a.m. LLC is actively or continuously testing plug-ins, nor does it imply two forty four a.m. LLC has any responsibility to police plug-ins.

1. A plug-in that is malicious is considered a candidate for blacklisting.
2. A plug-in that is so buggy that it fails to function correctly most or all of the time is considered a candidate for blacklisting. For example, a plug-in designed to toggle Airplane mode for Android 2.3 will not function on Android 4.2, due to new Android security restrictions. Such a plug-in could be blacklisted.
3. A plug-in that interferes with the normal functioning of the user's phone is a candidate for blacklisting. For example, a plug-in setting to reboot the user's device could potentially be configured to cause a reboot loop effectively locking the user out of his device. If the user added this reboot plug-in to the Defaults in Locale then the device would reboot as soon as it finished booting. To avoid being blacklisted, such a plug-in would need to implement mechanisms to avoid a reboot loop, which might include a cool-down period after the last time it was fired or suppressing firing it after a boot.
4. A plug-in that interferes with the normal functioning of the host is considered a candidate for blacklisting. For example, a security plug-in which prevents the host's UI from launching by monitoring the Activity stack might be considered a candidate for blacklisting.
5. A plug-in that is malicious, for example uploading private data without disclosure, is a candidate for blacklisting.
6. A plug-in that contains serious security flaws is a candidate for blacklisting. One example would be a plug-in that stores unencrypted login credentials in Intent.EXTRA_BUNDLE. Plug-ins are required to store such credentials in their own app private storage, rather than in the Bundle. Another example would be a plug-in that logs credentials to logcat.
7. A plug-in that can cost the user a large amount of money is a candidate for blacklisting. For example, a plug-in that automatically sends SMS messages could rack up charges with each outgoing message. Such a plug-in should implement throttling to limit the total number of messages sent as a safeguard.

Once a plug-in is identified as a candidate for blacklisting, multiple attempts will be made to contact the plug-in developer via email, Google Play, or whatever other mechanism the developer provides for feedback. If the developer does not respond within 30 days, the plug-in may be blacklisted at the discretion of two forty four a.m. LLC. If the developer does respond and appropriately addresses all concerns, then the plug-in will be unblacklisted.

Returns:

True if the plug-in is blacklisted.

getAlternatives

public Collection<String> getAlternatives()

Determines whether a third party plug-in has an alternative first party implementation.

The UI may decide to inform the user that the first party implementation exists. This is not intended to prevent users from trying third party plug-ins, however it is intended to educate users that built-in functionality may already exist. Given the lack of a review process for plug-ins, often plug-in quality is below that of built-in functionality and educating the user generally improves the user experience without taking away choice.

Note: The first party implementation is not guaranteed to be available, and it is the caller's responsibility to handle such a case. For example, different hosts may have different first party implementations. As another example example, Locale contains a built-in Calendar condition but it is only available on API 14 or greater. When determining whether the user should be presented with alternatives to a third party plug-in, Locale must first determine whether the alternative is actually available or not.

Returns:

A set of possible first-party implementation registry names. This set has consistent iteration ordering and may have been wrapped in call to Collections.unmodifiableSet(java.util.Set).

describeContents

public int describeContents()

Specified by:

describeContents in interface Parcelable

writeToParcel

public void writeToParcel(Parcel dest,
                          int flags)

Specified by:

writeToParcel in interface Parcelable

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object