Accessing Android Application Settings

The application developer cannot instantiate the ApplicationSettings class directly, it is instantiated by the LogonCore component.
An instance of this class is available via a LogonCore instance, only if the device is registered with the LogonCore component.

The ApplicationSettings class implements the IReadOnlyDictionary interface (or the equivalent interface/class on other platforms). This allows the application developer to:

Iterate through all the stored settings.
Use setting names to retrieve setting values.

The ApplicationSettings class guarantees that if an ApplicationSettings instance is available, it is in a consistent and valid state; the values this class stores are validated against a metadata document.

The application developer cannot modify the application settings directly, which is guaranteed by:

Implementing the IReadOnlyDictionary interface that provides read-only access to the settings container (new values cannot be added to the settings).
Storing values that implement the IReadOnlyProperty interface, which provides read-only access to the individual setting values.

Downloading Application Settings Method

This method:

Asynchronously downloads the application settings and metadata of the settings structure from mobile service for development and operations or SAP Mobile Platform Server.
Validates the downloaded settings against the newly downloaded metadata and persists the new settings and metadata.
Always succeeds and never sends a request if the LogonCore is used with Gateway.

public void downloadAppSettings();

Updating Writable Application Settings on the Server

This method:

Returns the copy of the writable application setting values in a non-mutable dictionary.
Guarantees that the application developer cannot edit the application settings directly; the settings stay consistent and valid on the client. However, the application developer can get the mutable version of the settings that are writable, so some or all of those values can be updated on the server.
Since properties (objects that store individual settings) cannot be instantiated by application developers, use this method to get access to the writable properties.
Only copies of the writable setting values are returned, guaranteeing that modification of the copied properties are not reflected in the stored application settings on the client.

public HashMap<String, AppSettingsProperty> getWriteableSettings();

Sample Code

var deviceType = logonCore.ApplicationSettings["DeviceModel"].Value as string;

// Assume the returned value is "Lenovo T530"
// Make a request for the writable settings and modify the same property:

var writableSettings = logonCore.ApplicationSettings.GetWritableSettings();
writableSettings["DeviceModel"].Value = "Surface Pro 3";

// The two properties do not hold the same value; "false" is printed
System.Diagnostics.Debug.WriteLine(logonCore.ApplicationSettings["DeviceModel"].Value == writableSettings["DeviceModel"]);

The writable values are modified on the client in the ApplicationSettings instance only if the modified values are sent to the server, and the server confirms that these values have been updated on the server side. This prevents the application settings from being overwritten on the client.

Send the Modified Writable Settings to the Server Method

This method:

Sends the modified writable settings to mobile service for development and operations or SAP Mobile Platform Server to asynchronously update server-side settings.
Requires the application developer to call the GetWritableSettings method, prior to calling this method, to access the writable properties that hold individual setting values.
Does not send requests to the server and always fails, stating that there are no modifications to the settings, if the LogonCore is used with Gateway.

This method ensures that:

Only the modified properties are sent to the server.
If updating the writable settings fails, then the application settings remain valid and consistent on the client.
After successfully updating the writable settings on the server, the settings are downloaded again to ensure that the application settings on the client are in sync with the settings stored on the server. This is necessary since the server might not accept all the values, but still reports success, or modification to one of the property values implies another requires change. Another example: there are nullable boolean values, but sending null in these values results in the server changing these null values to false.

public void updateAppSettings(HashMap<String, AppSettingsProperty> newSettings);

Updating Device Information on the Server

Although device information such as model type, subtype, and phone number can be updated by calling the GetWritableSettings method, modifying the relevant properties then calling the UpdateSettingsAsync method, a helper method that supports this particular scenario has been added to the API. This (helper) method offers these benefits to the application developer:

No need to call the GetWritableSettings method.
No need to know the application setting names that belong to the device settings group.
Can use dedicated properties of a class (DeviceInfo) instead of defining device specific settings. The method updates the device settings asynchronously on mobile service for development and operations or SAP Mobile Platform Server, and fails if called when using a Gateway connection.

The method accepts a DeviceInfo class instance.

The method should consider only those properties of the DeviceInfo class that have been modified by the application developer, which prevents device information which contain null values on the server that have not been modified by the application developer from being updated.

public void updateDeviceInfo(DeviceInfo deviceInfo)

Application Connection ID Property

This property:

Always returns null if a Gateway connection is used or if the device is not registered
Returns the application connection ID from the settings that can normally be found under the "ApplicationConnectionId" key, if the device is registered on mobile service for development and operations or SAP Mobile Platform Server
Is read-only

// retrieve connection id
String connectionId = logonCore.getAppSettings().getApplicationConnectionId();
// retrieve a setting value without dedicated property
String applicationVersion = (String)logonCore.getAppSettings().getSettingProperties().get(AppSettings.APPLICATION_VERSION).getValue();
// update some setting values
AppSettings appSettings = logonCore.getAppSettings();

HashMap<String, AppSettingsProperty> writableSettings = appSettings.getWritableSettings();
writableSettings.get(AppSettings.DEVICE_MODEL).setValue("LG");
writableSettings.get(AppSettings.DEVICE_SUBTYPE).setValue("G4");

appSettings.setListener(new IAppSettingsUploadListener() {

@Override
public void updateAppSettingsFinished() {
// update success
}

@Override
public void updateAppSettingsFailed() {
// update failed
}
});
appSettings.updateAppSettings(writableSettings);

Obtaining the Application Endpoint URL

This property:

Returns null if the device is not registered
Returns the URL to the service document if a Gateway connection is used
Returns the proxy URL, which can be used to download the service document, if the device is registered on mobile service for development and operations or SAP Mobile Platform Server
Is read-only

public URL getApplicationEndPointURL();

Obtaining the Latest mobile service for development and operations Version

To support the latest mobile service for development and operations version and features of the version 4 registration service, the UserName property returns a string from mobile service for development and operations.

Note The registrationServiceVersion setter in the LogonCore and the latest registration service version will be deprecated. These features should not be used, and instead use the default behavior, which handles all registration service versions and uses the latest available version of the server. Version 4 related server-side properties are accessible from ApplicationSettings using the getter method of the dictionary. Refer to Application Connection Properties for a list of mobile service for development and operations properties.

Information about the userName property can be found in the ApplicationSettings section of the Logon API documentation.

IReadOnlyProperty

The interface inherits from the IMetaProperty interface. A class that implements this interface must be constructed using a class that implements the IMetaProperty interface; properties can be created only from metadata and a value. This ensures that no ad hoc properties are created internally at runtime and that if a property is created it holds a valid value. No instances can be created that are in an inconsistent state (by holding a value that does not match the metadata restrictions defined in the metaproperty instance).
The interface extends the IMetaProperty interface with one Value property that holds a valid value that was validated against the metadata at construction time. After constructing the property its value and its metadata cannot be changed.
The application developer can access only IReadOnlyProperty instances when accessing the application settings. This ensures that application settings are not overwritten on the client side by the application developer.

Properties of this interface:

IsNullable
Indicates whether the value of a property can be null or not. For details, see the OData specification
```
public boolean isNullable();
```
Name
Represents the name of one application setting. For details about restrictions and rules on naming an OData property see the OData specification. It is a read-only property:
```
public String getName();
```
Type
Represents the type of the value of the property. The PropertyType type is an enumeration that defines the following constants as enum values: String, Boolean, Byte, Int8, Int16, Int32, Int64, Double, Single and Complex. An application developer can use this information to cast the generic "object" type of the "Value" property to get the typed value of a setting. When a property is a complex property (in OData terms) this "Type" property (in programming language terms) is set to Complex and the type name of the complex property is saved in the TypeName property. An application developer should check the Type and the CollectionKind properties to safely cast a property (app setting) value to a type supported by the programming language. If the CollectionKind property is set to the Collection enum value, then the value of the setting property is a read-only list of either a primitive (string, bool, int32 and so on) or a complex type. The PropertyType enumeration value might be extended by further primitive types (such as DateTime) if needed.
```
public PropertyType getType();
```
TypeName
This property holds the OData name of the type of the property. The value is never null and is read-only.
```
public String getTypeName();
```

IProperty

The class that implements this interface can be instantiated only internally by the application settings component, and the class grants write access to the setting that is stored locally. An application developer can get instances of the class that implement this interface only by calling the GetWritableSettings method. If the application developer has a reference to an instance of a class that implements this interface, the ApplicationSettings component guarantees that the Value property contains a copy of the application setting value of the original property. This means that even if the property value is set by the application developer the value is not reflected in the ApplicationSettings component thus guaranteeing a consistent and valid state of settings.
To modify a writable setting, the application developer must pass the read-only dictionary of <string, IProperty> instance retrieved by calling the GetWritableSettings method to the UpdateSettingsAsync method.
If an invalid value is set (a value that does not fulfill the metadata restriction for the given property) an exception is thrown.