9 Configuring End Points Used in MAF Applications

9.1 Introduction to Configuring End Points

The Configuration Service is a tool that allows you to configure end points used by web services, login utilities, and any other parts of a MAF application.

9.2 Defining the Configuration Service End Point

The end point (or seed) 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 (or seed) URL and its name set to an arbitrary value which will eventually be referenced in a Java bean code.

Example 9-1 shows how to define the Configuration Service end point in the connections.xml file.

<Reference name="ConfigServiceConnection" 
                className="oracle.adf.model.connection.url.HttpURLConnection"
                credentialStoreKey="ConfigServiceConnection"
                adfCredentialStoreKey="ConfigServerLogin"
                xmlns="">
   <Factory className="oracle.adf.model.connection.url.URLConnectionFactory"/>
   <RefAddresses>
      <XmlRefAddr addrType="ADFMFSecuredConfigServer">
         <Contents>
            <urlconnection name="ADFMFSecuredConfigServer" 
                           url="http://127.0.0.1"/>
               <authentication style="challange">
                 <type>basic</type>
                 <realm>myrealm</realm>
               </authentication>
            </urlconnection>
         </Contents>
      </XmlRefAddr>
      <SecureRefAddr addrType="username"/>
      <SecureRefAddr addrType="password"/>
   </RefAddresses>
</Reference>
<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"/>
            <accessControl url=""/>
            <idleTimeout value="300"/>
            <sessionTimeout value="28800"/>
            <authenticationMode value="remote"/>
            <rememberCredentials>
               <enableRememberUserName value="true"/>
               <rememberUserNameDefault value="true"/>
               <enableRememberPassword value="false"/>
               <enableStayLoggedIn value="true"/>
               <stayLoggedInDefault value="true"/>
            </rememberCredentials>
            <userObjectFilter/>
         </Contents>
      </XmlRefAddr>
   </RefAddresses>
</Reference>

If security is enabled for the configuration server, the connections.xml file would have to include the following additional definition:

• There should be a login connection that points to the same end point (or seed) URL as the URL connection. The login connection and HttpURLConnection should share the same adfCredentialStoreKey.

Sometimes the end point URL needs to be retrieved from the end user and cannot be set in the connections.xml file. If this is the case, a user interface can be created to obtain the value of the end point URL and set it into an application preference whose value can then be used in the Java bean method to override the connection URL value, as Example 9-2 shows.

AdfmfJavaUtilities.overrideConnectionProperty("ConfigServerConnection",
                                              "login",
                                              "url",
                                              <Endpoint_URL>);

9.3 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 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 allowing to associate the configuration server connection and the end point URL:

  _configservice.setDeliveryMechanismConfiguration("connectionName",
                                                   "ConfigServerConnection");
  _configservice.setDeliveryMechanismConfiguration("root", <Endpoint_URL);
  

• 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 hardcoded value or obtained through the Application.getApplicationVersion API:

  _configservice.stageAndActivateVersion("1.0");
  
  _configservice.stageAndActivateVersion(Application.getApplicationVersion);
  

• addProgressListener method registers an update progresslistener 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);
  

For more information, see Java API Reference for Oracle Mobile Application Framework.

9.4 About the URL Construction

The URL to each of the Configuration Service-managed resources is constructed. It contains the application ID and the file name as follows:

If the user provides the URL of http://my.server.com:port/SomeLocation and the application ID of com.mycompany.appname, the following t URLs will be used to download the configuration files:

http://my.server.com:port/SomeLocation/com.mycompany.appname/connections.xml
http://my.server.com:port/SomeLocation/com.mycompany.appname/maf-config.xml
http://my.server.com:port/SomeLocation/com.mycompany.appname/maf-config.xml

9.5 Setting Up the Configuration Service on the Server

The Configuration Service can be implemented as a service that accepts HTTP GET request and returns the connections.xml file.

The URL used by the Configuration Service client is of 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.

9.6 Migrating the Configuration Service API

If an application was created using the previous release of MAF and that application utilizes the Configuration Service, you have to perform manual migration.

The main reason for the migration is that in the current release, MAF removed support for the following APIs, properties, and utilities that played an essential role in enabling functionality of the Configuration Service:

• MAF used to provide means to manipulate the Configuration Service from the adf-config.xml file by setting the use-configuration-service-at-startup property to enable the service and adfmf-configuration-service-seed-url property to provide the end point URL.

• The checkForUpdates API provided means to check for the Configuration Service updates.

• The Configuration Service was initiated from a UI provided by MAF.

To start the migration, the end point (or seed) 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 9.2, "Defining the Configuration Service End Point."

Since in the current release MAF does not provide a user interface for the Configuration Service, you have to create it in a new or existing application feature assuming there is a requirement for the user interface. For more information, see Section 9.3, "Creating the User Interface for the Configuration Service."