X

Best Practices from Oracle Development's A‑Team

Updating MAF Connection Targets At Run Time

Introduction

Since resource targets (e.g. database, REST, .etc) defined in the connections.xml are set at development time and then deployed, this usually means that the target connections will be static.  However, there are certain situations where such a resource would need to be switched by the user at run time. For example, a user could pick from a list of server hosts that could support the mobile application's defined REST connection. The good news is that implementing this type of behavior is easy with Oracle's Mobile Application Framework (MAF) support for defining User Preferences.

Main Article

User preferences are primarily used to enable the management of application specific features and/or behaviors. The preferences can be configured by end users and are located in the Settings options of the mobile device. Examples of a user preference could be: the setting of the default text, changing the default background of the application or maybe disabling a certain feature. In Oracle MAF, within both the maf-application.xml and maf-feature.xml files, the user preference are defined as pages using the <adfmf:preferences> element. User preferences defined in the maf-application.xml file are considered general preferences. Specific (MAF) feature preferences, which overrides general preferences, are defined in the maf-feature.xml file. For more information please refer to the documentation. The following displays some of the typical preferences that can be developed in MAF:

appwidesettings1

The introduction section of this post mentions a use case that would enable the switching of the defined (REST) connection. This post will now detail how this can be accomplished in MAF using an application level preference.

Creating Mobile Application-Level Preferences

In JDeveloper, open the maf-application.xml file (located in the Application Resources > ADF META-INF folder).  Click on the Preferences link on the left pane. This will then display the overview editor. The overview editor enables you to build sets of application-level preference pages by nesting the child preference page elements within <adfmf:preferenceGroup>. The page presents the <adfmf:preferenceGroup> and its child elements as similarly named options. For example, in the previous screen shot above, there are two preference groups: APP PREFERENCES and F1 PREFERENCES, which are defined in the default preference page.  In addition, a preference page <adfmf:preferencePage> (e.g. APP Page) is also defined within the APP PREFERENCES group.

For this demo, the application will have one preference group with a child preference page. Within the child preference page, there will be another preference group, which will contain the list of servers can be selected. To start click on the (Green) Add (+) drop down list.

Note: To ensure that the maf-application.xml file is well-formed, use the Preferences page's Add drop down list to construct the user preferences pages. It is permitted to drag components from the Preferences palette into either the editor, the Source window, or the Structure window. However, the page's drop down list presents only the elements that can have the appropriate parent, child, or sibling relationship to a selected preferences element.

Screen Shot 2015-01-26 at 10.00.40 AM

Since the preferences are on the (default) preference page, the only option available is to insert a preference group.  Complete the information in the Insert Preference Page Group dialog.  For example: Id=mainsettings and Label=Main Settings.  Click OK to save the changes.

Screen Shot 2015-01-26 at 10.40.12 AM

The over view editor now displays the added preference group:

Screen Shot 2015-01-26 at 10.43.25 AM

The next step is to create another preference page, where the (REST) server list will be defined. In the over view editor, select the (Main Settings) preference group and click on the Add drop down list. Notice the displayed context menu only offers the appropriate items that can be added to the preference group. Select Insert Inside Preference Group > Preference Page

Screen Shot 2015-01-26 at 10.49.22 AM

Complete the information in the Insert Preference Page dialog.  For example: id=restURLconn and label=REST Connection. Click OK to save the changes.

The next step is the add the list of REST servers.  However, before the list can be created, another preference group must be created first. In the over view editor, select the (REST Connection) preference page and click on the Add drop down list. Again, since this is a preference page, the only option available is a preference group. Select Insert Inside Preference Page > Preference Group.

Complete the information in the Insert Preference Group dialog. For example: Id=conn_select and Label=Select REST Connection. Click OK to save the changes. The over view editor should look like this:

Screen Shot 2015-01-26 at 11.04.32 AM

One the preference group has been created, the creation of the (REST) server list can be done. Select the (Select REST Connection) Preference Group and click on the Add drop down list. From the context menu, Select Insert Inside Preference Page > Preference List:

Screen Shot 2015-01-26 at 11.07.00 AM

Complete the information in the Insert Preference List dialog. For example: Id=connList and Label=Server List. Click OK to save the changes. The over view editor should look like this:

Screen Shot 2015-01-26 at 11.11.30 AM

The next step is to define the preference list. In the over view editor in the right pane, notice the Preference Value section. This is where the list-of-values are to be defined. Click on the (Green) Add in the Preference Value section. Complete the information in the Insert Preference Value dialog. For example: Name=Rest Server 1 and Value=http://someurl1.com. Click OK to save the changes. The over view editor should look like this:

Screen Shot 2015-01-26 at 11.24.00 AM

The addition of adding new (server) values can be completed by duplicating the previous step or you can switch to the source code view for the over view editor and the proceed to add any additional preference (list) value(s) there.  Note: ensure that each preference value item id is unique (the code editor will flag the error though):

Screen Shot 2015-01-26 at 11.31.50 AM

Once all of the value items have been added, go back to the over view (tab). Select one of the value items to be the Default item:

Screen Shot 2015-01-26 at 11.34.35 AM

The application can now be deployed and tested in either a real device or simulator/emulator.  For example, the following is the application running in a iOS simulator:

<adfmf:preferenceGroup id="mainsettings" label="Main Settings">

Screen Shot 2015-01-26 at 11.50.31 AM

<adfmf:preferencePage id="restURLconn" label="REST Connection">

<adfmf:preferenceGroup id="conn_select" label="Select REST Connection">

Screen Shot 2015-01-26 at 11.50.47 AM

<adfmf:preferenceList id="connList" label="Server List" default="http://someurl1.com">
   <adfmf:preferenceValue name="REST server 1" value="http://someurl1.com" id="pv1"/>
   <adfmf:preferenceValue name="REST server 2" value="http://someurl2.com" id="pv2"/>
   <adfmf:preferenceValue name="REST server 3" value="http://someurl3.com" id="pv3"/>
</adfmf:preferenceList>

Screen Shot 2015-01-26 at 11.51.00 AM

Implementation for Switching of Defined Connection

Now that the user preference is in place, the next step is to implement code that will: get the chosen connection and update the defined connection, which is defined in the applications' connections.xml.  For example, in the demo application there is a definition for the following REST connection:

<Reference name="MyDemoConnection" className="oracle.adf.model.connection.rest.RestConnection" credentialStoreKey="JCS"
             adfCredentialStoreKey="JCS" xmlns="">
    <Factory className="oracle.adf.model.connection.rest.RestConnectionFactory"/>
    <RefAddresses>
      <XmlRefAddr addrType="MyDemoConnection">
        <Contents>
      <restconnection name="MyDemoConnection" url="http://someurl1.com"/>
        </Contents>
      </XmlRefAddr>
    </RefAddresses>
  </Reference>

In the MAF JAVA API there is a method: overrideConnectionProperty which will enable the application to update the current defined connection (which is: someurl1.com and also the default list value). The complete signature for this method is:

public static void overrideConnectionProperty(String connectionId, String node, String property, Object value)

Where based on the demo application defined connection, the parameters for this method will be :
connectionId - The name of the connection reference : MyDemoConnection
node - name for the node of the overridden property : restconnection
property - name for the overridden property : MyDemoConnection
value - value for the overridden property : this will be the value that is retrieved from the chosen user preference

To retrieve the chosen user preference value, the MAF application will make use of a method found in the AdfmfJavaUtilities : evaluateELExpression. The following is the complete code implementation, which is defined in the application's LifeCycleListenerImpl class:

public void start() {
String urlconnection =
AdfmfJavaUtilities.evaluateELExpression(#{preferenceScope.application.mainsettings.restURLconn.conn_select.connList}").toString();        
AdfmfJavaUtilities.overrideConnectionProperty(“MyDemoConnection”, "restconnection", "url", urlconnection);             
}

 Note: The expression language uses references that are defined by the preferences tags (e.g. <adfmf:preferenceList id="connList"). This demo implements the code in the start() method of the LifeCycleListenerImpl. Overriding connections defined for security may have to use the activate().

Now when the application starts up, the LifeCycleListenerImpl will get called and invoke the code that updates the connection.  To update the connection again through the user preferences, the application must be shut down (e.g. not put in the background) and then restarted in order for the new user selection to used.

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha

Recent Content