Class Overview
ProfileManager gives the developer the ability to create a profile and to load it explicitly or to associate it to a loading condition to be automatically loaded.
A profile is a set of properties (Property) with their value.
The utility of a profile is that we can collect in it the setting of the properties we need for a
specific purpose and then we can load it explicitly calling loadProfile(String) or automatically when the loading condition is verified.
The loading condition is defined by a profile rule. There are two types of profile rules:
-
ProfileRuleType: the profile is loaded when an activity comes to
foreground.
The rule associates the profile to be loaded with an activity, or a list of activities, that must be in foreground.
This type of rule is created using the method addProfileRule(StringBuffer, String, String, ArrayList).
-
ProfileUrlRuleType: the profile is loaded when a specified URL is loaded by a given activity.
The rule associates the profile to be loaded with an activity, or a list of activities, and a regular expression (regex) that defines a valid URL.
This type of rule is created using the method addProfileUrlRule(StringBuffer, String, String, ArrayList, String).
A profile is identified by a symbolic name that must be unique on the device.
When a profile is created it is assigned a
PersistenceType that can be:
- Factory Reset Persistent, the file containing the profile will survive to a factory reset.
- Enterprise Reset Persistent, the file containing the profile will survive to an enterprise reset.
- Reboot Persistent, the file containing the profile will survive to a reboot.
A Factory Reset Persistent profile can only be preinstalled on the device by an Espresso OTA and cannot be deleted.
The creation of a profile is done in best effort with reference to the specified set of couples of property and value,
that is when a profile is created all the properties that are read-only or which are set to values outside the range of their allowed
values or which require a device reboot to be applied are ignored.
A profile is saved on the device in a json file with the following schema:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Profile Description Schema",
"description": "Schema of a profile.",
"type": "object",
"version": "2.0.0",
"definitions": {
"properties": {
"type": "array",
"items": { "$ref": "#/definitions/property" }
},
"property": {
"type": "object",
"properties": {
"id": {
"type": ["integer", "string"],
"description": "Unique integer identifier of the property.
The defining string can be used instead of the numeric value."
},
"value": {
"type": "string",
"description": "Value of the property. It is a string and
it will be parsed according to the specific type of the property.
Value for a CharacterProperty is the unicode format (i.e: \\uFFFF)."
}
},
"required": ["id", "value"]
},
},
"properties": {
"version": {
"type": "string",
"description": "Version of the schema. If you use this the value must be 2.0.0."
} ,
"description": {
"type": "string",
"description": "Short string describing the profile."
},
"properties": {
"$ref": "#/definitions/properties",
"description": "List of properties with their value."
}
}
}
As said a profile can be load in two different ways:
- manually, calling method
loadProfile(String);
- automatically, calling
addProfileRule(StringBuffer, String, String, ArrayList) or addProfileUrlRule(StringBuffer, String, String, ArrayList, String) to define a rule that associates the profile to an activation condition.
As soon as the condition is verified, the related profile is automatically loaded.
The previous configuration is restored when that condition is no more satisfied.
There can be only one profile automatically loaded at the time.
The method
loadProfile(String) fails if there is already a profile manually loaded.
It is allowed to have at the same moment a manually loaded profile and an automatically loaded profile.
When there is both a manually loaded profile and an automatically loaded profile the value of the properties belonging to both profiles
are set to the value specified in the automatically loaded profile. This is true no matter the order of load of the two profiles was.
The persistence type of a profile controls:
- the persistence to reboot or reset of the profile file saved on the device, but not the persistence of the applied profile configuration;
- the persistence to reboot or reset of the rules that associate the profile to activation conditions, if any.
A rule that associates a profile with persistence `REBOOT_PERSISTENT` to an activation condition will survive to a reboot but it will be deleted
by an enterprise or factory reset.
A rule that associates a profile with persistence `ENTERPRISE_RESET_PERSISTENT` to an activation condition will survice to a reboot
or enterprise reset but it will be deleted by a factory reset.
The configuration applied by an automatically loaded profile is automatically unloaded when the associated activation condition is no more satisfied
or the device restarts.
The configuration applied by a manually loaded profile is persistent to a reboot and must be explicitly unloaded.
To create a profile follow these steps:
- Obtain an instance of ProfileManager with
ProfileManager(Context);
- Create an HashMap and add it the couples {
PropertyID, value} to be set when applying the profile;
- Create the profile calling
createProfile(String, HashMap, String, PersistenceType).
ProfileManager pm = new ProfileManager(this);
HashMap map = new HashMap();
map.put(PropertyID.CODE128_ENABLE, "true"); // BooleanProperty
map.put(PropertyID.CODE128_LENGTH2, "10"); // NumericProperty
map.put(PropertyID.CODE128_GS1_USER_ID, String.format ("\\u%04x", (int)'a')); // CharacterProperty
map.put(PropertyID.CODE128_LENGTH_CONTROL, LengthControlMode.ONE_FIXED.toString()); // EnumProperty
map.put(PropertyID.LABEL_PREFIX, "pippo"); // TextProperty
pm.createProfile("profilo_128.json",
map,
"enable code128, disable datamatrix",
PersistenceType.ENTERPRISE_RESET_PERSISTENT);
To add a rule that automatically loads the profile profilo_128.json
when the application with package name com.datalogic.testprofilo1
comes to the foreground, follow these steps:
- Obtain an instance of ProfileManager with
ProfileManager(Context).
- Create a StringBuffer and initialize it with the preferred identifier to be used to register the rule.
- Create the rule calling
addProfileRule(StringBuffer, String, String, ArrayList).
ProfileManager pm = new ProfileManager(this);
StringBuffer rule1_name = new StringBuffer("rule_1");
pm.addProfileRule(rule1_name,
"profilo_1.json",
"com.datalogic.testprofilo1",
new ArrayList());
To define a rule that automatically loads the profile profilo_128.json when the app with package name com.datalogic.testprofilo1
comes to the foreground and accesses any URL under "https://www.datalogic.com", follow these steps:
- Obtain an instance of ProfileManager with
ProfileManager(Context).
- Create a StringBuffer and initialize it with the preferred identifier to be used to register the rule.
- Create the rule calling
addProfileUrlRule(StringBuffer, String, String, ArrayList, String).
ProfileManager pm = new ProfileManager(this);
StringBuffer rule1_name = new StringBuffer("rule_1");
pm.addProfileUrlRule(rule1_name,
"profilo_1.json",
"com.datalogic.testprofilo1",
new ArrayList(),
"^https://www\\.datalogic\\.com(/.*)?$");
To manually load the profile profilo_128.json follow these steps:
- Obtain an instance of ProfileManager with
ProfileManager(Context).
- Load the profile calling
loadProfile(String).
ProfileManager pm = new ProfileManager(this);
pm.loadProfile("profilo_1.json");
To get the identifier of the manually loaded profile, if any, follow these steps:
- Obtain an instance of ProfileManager with
ProfileManager(Context).
- Get the profile identifier calling
getLoadedProfile().
ProfileManager pm = new ProfileManager(this);
String profile = pm.getLoadedProfile();
To unload the manually loaded profile follow these steps:
- Obtain an instance of ProfileManager with
ProfileManager(Context).
- Unload the profile calling
unloadProfile().
ProfileManager pm = new ProfileManager(this);
pm.unloadProfile();
To delete the profile profilo_128.json follow these steps:
- Obtain an instance of ProfileManager with
ProfileManager(Context).
- Delete the profile calling
deleteProfile(String).
ProfileManager pm = new ProfileManager(this);
pm.deleteProfile("profilo_1.json");
To remove the rule "rule_1" follow these steps:
- Obtain an instance of ProfileManager with
ProfileManager(Context).
- Remove the rule calling
removeProfileRule(String).
ProfileManager pm = new ProfileManager(this);
pm.removeProfileRule("rule_1");
To get the list of all the profiles saved on the device follow these steps:
- Obtain an instance of ProfileManager with
ProfileManager(Context).
- Get the list calling
getProfilesList().
ProfileManager pm = new ProfileManager(this);
ArrayList<ProfileType> profileList = pm.getProfilesList();
To get the list of all the rules defined on the device follow these steps:
- Obtain an instance of ProfileManager with
ProfileManager(Context).
- Get the list calling
getProfileRulesList().
ProfileManager pm = new ProfileManager(this);
ArrayList<ProfileRuleType> profileRuleList = pm.getProfileRulesList();
