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 Propertys 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
an activity comes to foreground, defining a rule (addProfileRule(StringBuffer, String, String, ArrayList)) that associates that profile with the activity.
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 mode:
- manually, calling method
loadProfile(String),
- automatically, calling the method
addProfileRule(StringBuffer, String, String, ArrayList) to define a rule that associates the profile to a set of activities.
When one of the specified activities comes to the foreground
the profile will be automatically loaded. The previous configuration will be restored when the activity will be no more in foreground.
An activity can have only one profile associated.
Given their nature there can be only one profile automatically loaded at the time, because:
- there is the constraint on the definition of a rule to forbid for an activity to be associated to more than one profile, and
- there is only one activity in top foreground at a 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 file saved on the device not the persistence of the applied profile configuration, and
- the persistence to reboot or reset of the rules that associate the profile to activities, if any. A rule that associates a profile with persistence REBOOT_PERSISTENT to an activity will be recreated after a normal reset but will be deleted by an enterprise reset. A rule that associates a profile with persistence ENTERPRISE_RESET_PERSISTENT to an activity will be recreated after a normal or enterprise reset but will be deleted by a factory reset.
The configuration applied by an automatically loaded profile is automatically unloaded when the associated activity is no more in foreground 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 do the following steps:
- Obtain an instance of ProfileManager with
ProfileManager(Context).
- Create an HashMap and add it the couples {
PropertyID,value} to be set 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 to automatically load the profile profilo_128.json when the app with package com.datalogic.testprofilo1
comes to the foreground do the following 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 manually load the profile profilo_128.json do the following 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 profile manually loaded, if any, do the following 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 profile manually loaded do the following 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 do the following 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" do the following 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 do the following steps:
- Obtain an instance of ProfileManager with
ProfileManager(Context).
- Get the list calling
getProfilesList().
ProfileManager pm = new ProfileManager(this);
ArrayList profileList = pm.getProfilesList();
To get the list of all the rules defined on the device do the following steps:
- Obtain an instance of ProfileManager with
ProfileManager(Context).
- Get the list calling
getProfileRulesList().
ProfileManager pm = new ProfileManager(this);
ArrayList profileRuleList = pm.getProfileRulesList();
