Configuring End Points Used in MAF Applications

Introduction to Configuring End Points in MAF Applications

MAF provides the Configuration Service to configure end points used by web services, login utilities, and other components of MAF applications.

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.

Note:

MAF applications on the Universal Windows Platform do not support the use of the Configuration Service.

Defining the Configuration Service End Point

Defining the Configuration Service end point URL and a new connection entry in the connections.xml file constitute the definition of a Configuration Service end point.

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.

The following example shows how to define the Configuration Service 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"/>
          <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 the previous example shows.

Most of the time, the end point URL needs to be retrieved from the user. To address this use case, create a user interface to retrieve the value of the end point URL from the 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-1 shows.

Example 16-1 Overriding the Connection Definition

AdfmfJavaUtilities.clearSecurityConfigOverrides(<ConfigService_ConnectionName>);
AdfmfJavaUtilities.overrideConnectionProperty(<ConfigService_ConnectionName>, "urlconnection",
                                                               "url", <ConfigService_EndpointURL>);

// 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>);

// Final step is to apply the changes.
AdfmfJavaUtilities.updateApplicationInformation(false);

Creating the User Interface for the Configuration Service

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 configuration server of the previous release 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 information about the oracle.adfmf.config.client.ConfigurationService class, see Java API Reference for Oracle Mobile Application Framework.

About the URL Construction

The endpoint URL that the user provided or that was specified in theconnections.xml file is used by the Configuration Service to construct the URL to download the connections.xml file.

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

Setting Up the Configuration Service on the Server

The Configuration Service accepts HTTP GET requests and returns the connections.xml file.

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 adf-config.xml/application bundle id/connections.xml

The Configuration Service end point may be secured using basic authentication (BASIC_AUTH) over HTTP and HTTPS.