This chapter describes how to use the Configuration Service to configure end points that a MAF application can use.
This chapter includes the following sections:
Section 16.1, "Introduction to Configuring End Points in MAF Applications"
Section 16.2, "Defining the Configuration Service End Point"
Section 16.3, "Creating the User Interface for the Configuration Service"
Section 16.5, "Setting Up the Configuration Service on the Server"
Section 16.6, "Migrating the Configuration Service from ADF Mobile"
The Configuration Service is a tool that allows you to configure end points used by web services, login utilities, and other parts of MAF applications.
The end point URL is defined in the connections.xml file and a new connection entry must be added to that file. This new connection should be of type HttpURLConnection, with its url value pointing to the configuration server end point URL and its name set to an arbitrary value which will eventually be referenced in a Java bean code.
Example 16-1 shows how to define the Configuration Service end point in the connections.xml file.
Example 16-1 Setting End Point in the connections.xml File
<RefAddresses>
<XmlRefAddr addrType="ConfigServiceConnection">
<Contents>
<urlconnection name="ConfigServiceConnection" url="http://127.0.0.1"/>
</Contents>
</XmlRefAddr>
</RefAddresses>
</Reference>
<!-- Login Server connection for secured configuration service -->
<Reference name="ConfigServerLogin" className="oracle.adf.model.connection.adfmf.LoginConnection"
adfCredentialStoreKey="ConfigServerLogin" partial="false"
manageInOracleEnterpriseManager="true"
deployable="true" xmlns="">
<Factory className="oracle.adf.model.connection.adfmf.LoginConnectionFactory"/>
<RefAddresses>
<XmlRefAddr addrType="adfmfLogin">
<Contents>
<login url="http://127.0.0.1"/>
<logout url="http://127.0.0.1"/>
<authenticationMode value="remote"/>
<idleTimeout value="300"/>
<sessionTimeout value="28800"/>
<maxFailuresBeforeCredentialCleared value="3"/>
<injectCookiesToRestHttpHeader value="true"/>
<includeBasicAuthHeader value="true"/>
<rememberCredentials>
<enableRememberUserName value="true"/>
<rememberUserNameDefault value="true"/>
<enableRememberPassword value="false"/>
<enableStayLoggedIn value="false"/>
</rememberCredentials>
<accessControl/>
<userObjectFilter/>
</Contents>
</XmlRefAddr>
</RefAddresses>
If security is enabled for the configuration server, the connections.xml file has to include a login connection that points to the same end point URL as the URL connection. The login connection and HttpURLConnection should share the same adfCredentialStoreKey, as Example 16-1 shows.
Most of the time, the end point URL needs to be retrieved from the end user. To address this use case, create a user interface to retrieve the value of the end point URL from the end user and set it in an application preference. The retrieved value can then be used in a Java bean method to override the connection URL value, as Example 16-2 shows.
Example 16-2 Overriding the Connection Definition
AdfmfJavaUtilities.clearSecurityConfigOverrides(<ConfigService_ConnectionName>);
AdfmfJavaUtilities.overrideConnectionProperty(<ConfigService_ConnectionName>, "urlconnection",
"url", <ConfigService_EndpointURL>);
AdfmfJavaUtilities.addWhiteListEntry(AdfmfJavaUtilities.getFeatureId(),
<ConfigService_EndpointURL>, false);
// Required if Config Service is secured and the authentication endpoints are input by the user
AdfmfJavaUtilities.clearSecurityConfigOverrides(<ConfigService_AuthenticationConnectionName>);
AdfmfJavaUtilities.overrideConnectionProperty(<ConfigService_AuthenticationConnectionName>,
"login", "url", <Login_EndpointURL>);
AdfmfJavaUtilities.overrideConnectionProperty(<ConfigService_AuthenticationConnectionName>,
"logout", "url", <Logout_EndpointURL>);
AdfmfJavaUtilities.addWhiteListEntry(<Login_EndpointURL>, false);
AdfmfJavaUtilities.addWhiteListEntry(<Logout_EndpointURL>, false);
// Final step to apply the changes
AdfmfJavaUtilities.updateApplicationInformation(false);
If there is a requirement for the Configuration Service user interface, you should create it in a new or existing application feature.
MAF provides a set of APIs within the oracle.adfmf.config.client.ConfigurationService class that allow to check for new changes on the server and download the updates. You can use these APIs in a Java bean to activate the respective methods through the Configuration Service application feature.
In the following list of APIs and their sample usage, the _configservice variable represents an instance of the oracle.adfmf.config.client.ConfigurationService class:
setDeliveryMechanism method sets the delivery mechanism for the Configuration Service. Since the communication with the previous release's configuration server is enabled through HTTP, http is passed in as an argument to this method:
_configservice.setDeliveryMechanism("http");
Note:
The method argument refers to the web transport that is to be used for the Configuration Service and should not be confused with HTTP or HTTPS: if the end point is an HTTPS URL, setting the transport to http is still valid.setDeliveryMechanismConfiguration method sets additional attributes on the Configuration Service to associate the configuration server connection and the end point URL:
_configservice.setDeliveryMechanismConfiguration("connectionName",
<ConfigService_ConnectionName>);
isThereAnyNewConfigurationChanges method checks whether or not there are any changes on the server that are available for download, and if there are, this method returns true:
_configservice.isThereAnyNewConfigurationChanges(<APPLICATION_ID>, <VERSION>);
stageAndActivateVersion method triggers download of updates by the Configuration Service. The application version is passed in as an argument to this method, either as a hard-coded value or obtained through the Application.getApplicationVersion API:
_configservice.stageAndActivateVersion("1.0");
_configservice.stageAndActivateVersion(Application.getApplicationVersion);
addProgressListener method registers an update progress listener on the Configuration Service to receive update messages and progress status. The underlying class should implement the ProgressListener interface and the updateProgress method which is to be called from the Configuration Service. The updateProgress method receives the progress update message and the update percentage complete:
_configservice.addProgressListener(this);
removeProgressListener method unregisters the update progress listener:
_configservice.removeProgressListener(this);
The ConfigServiceDemo sample application demonstrates how to use these APIs to communicate with the configuration server. The ConfigServiceDemo application is located in the PublicSamples.zip file within the jdev_install/jdeveloper/jdev/extensions/oracle.maf/Samples directory on your development computer.
For more information about the oracle.adfmf.config.client.ConfigurationService class, see Oracle Fusion Middleware Java API Reference for Oracle Mobile Application Framework.
The Configuration Service takes the endpoint URL that the user provides or that is specified in the connections.xml file and uses it to construct the URL to download the connections.xml file.
For example, if a user provides the following endpoint URL for an application that has an application ID value of com.mycompany.appname:
http://my.server.com:port/SomeLocation
Then, the Configuration Service constructs the following URL to download the connections.xml file:
http://my.server.com:port/SomeLocation/com.mycompany.appname/connections.xml
The Configuration Service can be implemented as a service that accepts HTTP GET requests and returns the connections.xml file.
The URL used by the Configuration Service client is in the following format:
url configured in /connections.xml
The Configuration Service end point may be secured using basic authentication (BASIC_AUTH) over HTTP and HTTPS.
You have to perform a manual migration of the Configuration Service if you migrate an application that you created using ADF Mobile to MAF Release 2.0 or later.
MAF Release 2.0 removed support for the following APIs, properties, and utilities that enabled functionality of the Configuration Service:
The adf-config.xml file can no longer be used to enable the Configuration Service by setting the use-configuration-service-at-startup property or to provide the end point URL using the adfmf-configuration-service-seed-url property.
The checkForUpdates API that provided a way to check for Configuration Service updates is deprecated.
The Configuration Service was initiated from a UI provided by ADF Mobile.
The end point URL must be moved from the adf-config.xml file to the connections.xml file and a new connection element must be added to the connections.xml file, as described in Section 16.2, "Defining the Configuration Service End Point."
As part of the migration to this release of MAF, you create a user interface to retrieve the endpoint URL from the user and add a backing bean to invoke the Configuration Service APIs. For more information, see Section 16.3, "Creating the User Interface for the Configuration Service."
A MAF sample application called ConfigServiceDemo demonstrates how to use the APIs to communicate with the configuration server. The ConfigServiceDemo application is located in the PublicSamples.zip file within the jdev_install/jdeveloper/jdev/extensions/oracle.maf/Samples directory on your development computer.