to top
Datalogic APIs
public class

ProfileManager

extends Object
java.lang.Object
   ↳ com.datalogic.device.configuration.ProfileManager

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:

  1. Factory Reset Persistent, the file containing the profile will survive to a factory reset.
  2. Enterprise Reset Persistent, the file containing the profile will survive to an enterprise reset.
  3. 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:

  1. manually, calling method loadProfile(String),
  2. 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:

  1. there is the constraint on the definition of a rule to forbid for an activity to be associated to more than one profile, and
  2. 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:

  1. the persistence to reboot or reset of the file saved on the device not the persistence of the applied profile configuration, and
  2. 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:
  1. Obtain an instance of ProfileManager with ProfileManager(Context).
  2. Create an HashMap and add it the couples {PropertyID,value} to be set applying the profile.
  3. 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:
  1. Obtain an instance of ProfileManager with ProfileManager(Context).
  2. Create a StringBuffer and initialize it with the preferred identifier to be used to register the rule.
  3. 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:
  1. Obtain an instance of ProfileManager with ProfileManager(Context).
  2. 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:
  1. Obtain an instance of ProfileManager with ProfileManager(Context).
  2. 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:
  1. Obtain an instance of ProfileManager with ProfileManager(Context).
  2. Unload the profile calling unloadProfile().
 ProfileManager pm = new ProfileManager(this);
 pm.unloadProfile();
 
To delete the profile profilo_128.json do the following steps:
  1. Obtain an instance of ProfileManager with ProfileManager(Context).
  2. 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:
  1. Obtain an instance of ProfileManager with ProfileManager(Context).
  2. 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:
  1. Obtain an instance of ProfileManager with ProfileManager(Context).
  2. 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:
  1. Obtain an instance of ProfileManager with ProfileManager(Context).
  2. Get the list calling getProfileRulesList().
 ProfileManager pm = new ProfileManager(this);
 ArrayList profileRuleList = pm.getProfileRulesList();
 

Summary

Public Constructors
ProfileManager(Context context)
This is the constructor of ProfileManager.
Public Methods
int addProfileRule(StringBuffer name, String profile, String packageName, ArrayList<String> classes)
Creates a rule to automatically load the given profile when one of the specified activities comes to foreground.
int createProfile(String name, File profile, PersistenceType persistence)
Creates the profile with the given name and the specified persistence type.
int createProfile(String name, HashMap<Integer, String> map, String description, PersistenceType persistence)
Saves the given map as a profile with the specified name, description and persistence type.
int deleteProfile(String name)
Deletes the given profile.
String getLoadedProfile()
Returns the name of the manually loaded profile, otherwise an empty string.
ArrayList<ProfileRuleType> getProfileRulesList()
Gets the list of all the profile rules defined on the device.
ArrayList<ProfileType> getProfilesList()
Gets the list of all the profiles saved on the device.
int loadProfile(String name)
Applies the given profile.
int removeProfileRule(String name)
Delete the specified rule.
int unloadProfile()
Revert the manually loaded profile restoring the values previously set on the device.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public ProfileManager (Context context)

Added in revision 32

This is the constructor of ProfileManager.

Parameters
context Context context of the caller application
Throws
ConfigException in case of error.

Public Methods

public int addProfileRule (StringBuffer name, String profile, String packageName, ArrayList<String> classes)

Added in revision 32

Creates a rule to automatically load the given profile when one of the specified activities comes to foreground. The specified activities must all belong to the same package. When the activity is no more in foreground the previous configuration is restored.
A rule is uniquely identified by its name which must therefore be unique. In input, through parameter name, you can specify the name to be associated with the rule. If name is unique it is used, otherwise the method makes it unique adding it a suffix. The caller can learn the string used to name the rule because the StringBuffer object name is updated.
The profile associated to the rule is the one found with the given name. There must be only one rule to be loaded when an activity comes to the foreground. If one of the specified activities already has an associated profile the method fails.
The persistence to reboot of a rule is that of the referred profile. If the referred profile is deleted by reboot all the rules in which it is referred are deleted.

Parameters
name StringBuffer in input an empty string or the preferred name for the rule, in output the unique name assigned to the rule; if the value in input is unique and not empty is the value used otherwise the method makes it unique adding a suffix.
profile String the name of the profile to be loaded when one of the given activities comes to foreground.
packageName String name of the package containing the given activities.
classes ArrayList list of class names inside of the package for which the profile must be loaded. If the list is empty it means all the classes of the package.
Returns
  • int SUCCESS in case of success, otherwise a possible error code, matching one of the ConfigException error constants.
Throws
ConfigException in case of error, when exceptions are enabled through the ErrorManager singleton.

public int createProfile (String name, File profile, PersistenceType persistence)

Added in revision 32

Creates the profile with the given name and the specified persistence type.
If a profile with the same name is already present the method fails.
The schema of the profile file is:

 {
  "$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."
      }
  }
 }
 

Parameters
name String name to be used to create the profile file. The name must have the ".json" extension, otherwise it is added by the method.
profile File file of the profile to be saved on the device. The file must have the schema shown above.
persistence PersistenceType the persistence mode assigned to the profile file to be created. Only REBOOT_PERSISTENT and ENTERPRISE_RESET_PERSISTENT are allowed. It is not possible to create a profile with FACTORY_RESET_PERSISTENT persistence. A Factory Reset Persistent profile can only be preinstalled on the device by an Espresso OTA and cannot be deleted.
Returns
  • int SUCCESS in case of success, otherwise a possible error code, matching one of the ConfigException error constants.
Throws
ConfigException in case of error, when exceptions are enabled through the ErrorManager singleton.

public int createProfile (String name, HashMap<Integer, String> map, String description, PersistenceType persistence)

Added in revision 32

Saves the given map as a profile with the specified name, description and persistence type. If a profile with the same name is already present the method fails.
The profile file is a .json file with the schema shown in createProfile(String, File, PersistenceType).

Parameters
name String name to be used to create the profile file. The name must have the ".json" extension, otherwise it is added.
map HasMap map of properties with their value to be saved as profile.
description String description to be associated to the profile.
persistence PersistenceType the persistence mode to be assigned to the profile. Only REBOOT_PERSISTENT and ENTERPRISE_RESET_PERSISTENT are allowed. It is not possible to save a profile with FACTORY_RESET_PERSISTENT persistence.
Returns
  • int SUCCESS in case of success, otherwise a possible error code, matching one of the ConfigException error constants.
Throws
ConfigException in case of error, when exceptions are enabled through the ErrorManager singleton.

public int deleteProfile (String name)

Added in revision 32

Deletes the given profile. The method fails if the profile has FACTORY_RESET_PERSISTENT persistence or it is currently loaded or it is associated to a rule.

Parameters
name String name of the profile file to be deleted.
Returns
  • int SUCCESS in case of success, otherwise a possible error code, matching one of the ConfigException error constants.
Throws
ConfigException in case of error, when exceptions are enabled through the ErrorManager singleton.

public String getLoadedProfile ()

Added in revision 32

Returns the name of the manually loaded profile, otherwise an empty string.

Returns
  • String, the name of the manually loaded profile or an empty String if there isn't a manually loaded profile.

public ArrayList<ProfileRuleType> getProfileRulesList ()

Added in revision 32

Gets the list of all the profile rules defined on the device.

Returns
  • ArrayList<ProfileRuleType> in case of success, otherwise, if exceptions are not enabled, a null pointer.
Throws
ConfigException in case of error, when exceptions are enabled through the ErrorManager singleton.

public ArrayList<ProfileType> getProfilesList ()

Added in revision 32

Gets the list of all the profiles saved on the device.

Returns
  • ArrayList<ProfileType> in case of success, otherwise, if exceptions are not enabled, a null pointer.
Throws
ConfigException in case of error, when exceptions are enabled through the ErrorManager singleton.

public int loadProfile (String name)

Added in revision 32

Applies the given profile. If there is already a manually loaded profile the method fails. The properties listed in the profile are set to the values specified in the profile. The changes done to the configuration loading the profile are persistent to the reboot of the device. To unload the profile the method unloadProfile() must be invoked.

Parameters
name String name of the profile file to be loaded.
Returns
  • int SUCCESS in case of success, otherwise a possible error code, matching one of the ConfigException error constants.
Throws
ConfigException in case of error, when exceptions are enabled through the ErrorManager singleton.

public int removeProfileRule (String name)

Added in revision 32

Delete the specified rule.

Parameters
name String name of the rule to be deleted.
Returns
  • int SUCCESS in case of success, otherwise a possible error code, matching one of the ConfigException error constants.
Throws
ConfigException in case of error, when exceptions are enabled through the ErrorManager singleton.

public int unloadProfile ()

Added in revision 32

Revert the manually loaded profile restoring the values previously set on the device. It fails if there isn't a profile manually loaded.

Returns
  • int SUCCESS in case of success, otherwise a possible error code, matching one of the ConfigException error constants.
Throws
ConfigException in case of error, when exceptions are enabled through the ErrorManager singleton.