Skip Headers
Oracle® Communications Converged Application Server Developer's Guide
Release 5.1

Part Number E27707-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

19 SFT Deployment Descriptor and Schema Reference

Deployment descriptors are XML Schema Definition-based (XSD). The following sections describe XSD-based deployment descriptors and namespace declarations for the Service Foundation Toolkit (SFT) for Converged Application Server.

Application-Based Deployment

An application is a logical collection of one or more modules joined by application annotations or deployment descriptors. You assemble components into WAR or SAR files which are then deployed within a Converged Application Server installation using the SFT domain template.

XML Schema Definitions and Namespace Declarations

The contents and arrangement of elements in the sft.xml deployment descriptor file must conform to the appropriate XSD. An XSD deployment descriptor file requires a namespace declaration in the root element of the file. Namespace declarations in the root element of a deployment descriptor file apply to all elements in the descriptor unless a specific element includes another namespace declaration that overrides the root namespace declaration.

Oracle recommends that you always include the schema location URL along with the namespace declaration in your XML deployment descriptor files; if you do not include the schema location in your XML deployment descriptor files, you may not be able to edit the descriptor files with a third-party tool.

Annotation-based Configuration

An alternative to XML-based deployment descriptors is provided by annotation-based configuration, which injects metadata for configuring components into the Java class byte code instead of using XML-based deployment descriptors. Instead of using XML to describe a Java bean, the configuration information is contained within the Java class itself by using annotations on the relevant class, method, or field declaration.

This annotation indicates that the affected bean property be populated at runtime time through an explicit property value in the bean definition.

Using the @ServiceAttributes Annotation

The @ServiceAttributes annotation is placed at top of a @CommunicationBean annotation. There can only one @ServiceAttribute annotation in an application. @ServiceAttributes defines the attributes of the application. Example 19-1 illustrates the use of the @ServiceAttributes annotation to specify bandwidth usage supplementary service. To lean about the @ServiceAttributes annotation, refer to the Converged Application Server API Reference

Example 19-1 Specifying Bandwidth With The @ServiceAttributes Annotation

@ServiceAttributes(enableChangeBandwidth = true, sdpBandwidthAttributes = 
{0, 800, 1600})

About the sft.xml Deployment Descriptor Elements

The following sections describe the elements in the Converged Application Server-specific deployment descriptor sft.xml.

About the communication-bean Element

The communication-bean element describes the CommunicationBean and other resources used by the SFT application. If a CommunicationBean using the class name specified with the class-name element exists, then the name and type values override the values specified using the annotations in the CommunicationBean's Java class file.

If the event element specified in the communication-bean element matches the CommunicationBean's annotated method (it uses the same communication-type and event-type), then the orchestration priority value specified with the orchestration element overrides the value specified in the CommunicationBean Java class file.

Table 19-1 describes the elements you can define within the communication-bean element.

Table 19-1 Sub-Elements of the communication-bean Element

Element Description

name

Name of the CommunicationBean. If a name is not specified, the SFT container uses the fully-qualified class name as the CommunicationBean name. This procedure is typically used to enable configuration of Java beans within the application server.

class-name

The fully-qualified name of the Java class. For example:

<class-name>com.oracle.sft.CommunicationBean</class-name>

type

Identifies the type of CommunicationBean. If the type is specified, the CommunicationBean is invoked only for the specified event types. If the application does not specify an event type, then the CommunicationBean is invoked for any type of communication session. The type values are:

  • Conversation

  • Conference

  • IMConversation

  • IMConference

  • MSRPConversation

  • MSRPConference

  • MessageObservation

  • QueryInteraction

For example:

<type>Conversation</type>

event

Identifies events pertaining to the type of communication. The possible values are those defined using the following method-level event annotations:

  • CommunicationEvent

  • ParticipantEvent

  • ProtocolEvent

Refer to the Converged Application Server API Reference for information on the event types.

For example:

<event communication-type="Conversation" 
event-type="ParticipantEvent.Type.JOINING">
</event>

communication-type

Identifies the type of communication to which to apply the communication event. The communication-type values are:

  • Conversation

  • Conference

  • IMConversation

  • IMConference

  • MSRPConversation

  • MSRPConference

  • MessageObservation

  • QueryInteraction

event-type

Identifies events pertaining to the type of communication. The possible values are those defined using the ParticipantEvent.Type and CommunicationEvent.Type:

  • CommunicationEvent

  • ParticipantEvent

  • ProtocolEvent

Refer to the Converged Application Server API Reference for information on the event types.

For example:

<event communication-type="Conversation" 
event-type="ParticipantEvent.Type.JOINING">
</event>

Example 19-2 Example communication-bean Element

<communication-bean>
    <name>ConversationBean</name>
    <class-name>com.oracle.sft.ConversationBean</class-name>
    <type>Conversation</type>
    <event communication-type="Conversation"
        event-type="ParticipantEvent.Type.JOINING">
        <orchestration priority="10" />        
   </event>
  </communication-bean>

The service-attributes Element

Service attributes define various configuration parameters for use by SFT applications. You can specify these parameters using either the service-attributes element in the sft.xml deployment descriptor, or using the @ServiceAttributes annotation placed in the CommunicationBean's Java class file. If you specify service parameters using the service-attributes element in the sft.xml deployment descriptor, the values you specify will override the values specified using the @ServiceAttributes annotation.

Table 19-2 describes the elements you can define within the service-attributes element.

Table 19-2 Sub-Elements of the service-attributes Element

Element Description

registrar

The IP address or DNS name of the Registrar to use in conjunction with SFT.

domain-proxy

The IP address or DNS name of the Domain Proxy to use in conjunction with SFT.

domain-name

Specifies the default domain name, which is appended to all user names.

xcap-root

Specifies the HTTP URI representing the XCAP root. Although a syntactically valid URI, the XCAP Root URI does not correspond to an actual resource on an XCAP server. Actual resources are created by appending additional path information to the XCAP Root URI.

mscontrol-jndi-name

Java Naming and Directory Interface (JNDI) name with which to look up the MsControlFactory object configured for use with the application server. This allows you to use different Media Servers or configurations for the default MsControlFactory object.

enableChangeBandwidth

Specifies whether or not to enable the alternate bandwidth settings specified by the sdpBandwidthAttributes element (see below). By default, enableChangeBandwidth is set to “true”:

<enableChangeBandwidth>true</enableChangeBandwidth>

The 3GPP TS 24.610 specification requires that the application server (AS) of the User Equipment (UE) invoking a media stream whose SDP session attribute is “recvonly” use a lower bandwidth. The 3GPP TS 24.610 specification recommends these values to preserve network bandwidth when a communication is placed on hold, however, you may need to adjust the bandwidth to better suit the requirements of the Communication Hold application.

See "Setting the Communication Hold Bandwidth" for more information.

sdpBandwidthAttributes

The 3GPP 24.610 Communication HOLD specification specifies that, as a network option, the AS of the UE that invokes Communication HOLD shall, for each media stream marked “recvonly,” lower the bandwidth by setting the “b=AS:” parameter to a lower value. For example, the “b=AS:0”. The “b=RR:” and “b=RS:” parameters are set to values large enough to enable the continuation of the RTCP flow. For example, “b=RR:800” and “b=RS:800”.

Elements you can define within the sdpBandwidthAttributes element are:

  • totalBandwidth

  • bandwidthForActiveDataSenders

  • bandwidthForOtherParticipants

For example:

<sdpBandwidthAttributes>
   <totalBandwidth>0</totalBandwidth>
   <bandwidthForActiveDataSenders>800</bandwidthForActiveDataSenders>
   <bandwidthForActiveDataSenders>800</bandwidthForActiveDataSenders>
</sdpBandwidthAttributes>

See "Setting the Communication Hold Bandwidth" for more information.

conferenceEventConfig

Specifies the configuration parameters for a conference event. Elements you can define within the conferenceEventConfig element are:

  • minExpirationTime

  • defaultExpirationTime

  • maxExpirationTime

  • maxNumOfSubscriptions

For example:

<conferenceEventConfig>
    <minExpirationTime>100</minExpirationTime>
    <defaultExpirationTime>1800</defaultExpirationTime>
    <maxExpirationTime>3600</maxExpirationTime>
    <maxNumOfSubscriptions>100</maxNumOfSubscriptions>
</conferenceEventConfig>

See "Configuring the Conference Event Package" for more information.

messageObservationEventConfig

Specifies the configuration parameters for a message waiting event. Elements you can define within the messageObservationEventConfig element are:

  • minExpirationTime

  • defaultExpirationTime

  • maxExpirationTime

  • maxNumOfSubscriptions

For example:

<messageObservationEventConfig>
    <minExpirationTime>100</minExpirationTime>
    <defaultExpirationTime>1800</defaultExpirationTime>
    <maxExpirationTime>3600</maxExpirationTime>
    <maxNumOfSubscriptions>100</maxNumOfSubscriptions>
</messageObservationEventConfig>

See "Configuring the Conference Event Package" for more information.

referEventConfig

Specifies the configuration parameter for a refer event. Note that unlike SUBSCRIBE, REFER does not contain a duration for the subscription in either the request or the response. The application can specify the default expiration time for a refer event. For example:

<referEventConfig>1800</referEventConfig>

terminatingOperator

Represents the term-ioi parameter in P-Charging-Vector header.

The P-Charging-Vector header allows IMS signaling elements to generate and/or query IMS Charging IDs (icid) and originating and terminating Inter Operator Identifiers (ioi). For more information refer to the 3GPP TS 24.229 and RFC 3455 specifications.

chargingCollectionFunction

Represents the Charging Collection Function (CCF) charging functional entity in P-Charging-Function-Addresses header. CCF is used for off-line charging (for example, postpaid account charging). Elements you can define within the chargingCollectionFunction element are

  • ccf

    For example:

    <chargingCollectionFunction>
          <ccf>10.182.99.71</ccf>
          <ccf>10.182.99.72</ccf>
        </chargingCollectionFunction>
    

eventChargingFunction

Represents the Event Charging Function (ECF) charging functional entity in P-Charging-Function-Addresses header. ECF is used for on-line charging (for example, pre-paid account charging). Elements you can define within the eventChargingFunction element are:

  • ecf

    For example:

    <eventChargingFunction>
          <ecf>10.182.99.71</ecf>
        </eventChargingFunction>
    

statusCode4InitiateEarlyMedia

Specifies the status code of the response through which the AS initiates early media for certain instances of the UserParticipant as the caller. Converged Application Server support two values: 183 (Session Progress) and 180 (Ringing). If a value is not specified, or the value is something other than either 183 or 180, 183 will be used by default.

<statusCode4InitiateEarlyMedia>183</statusCode4InitiateEarlyMedia>

Annotation Scanning

Annotation scanning can only be specified using the sft.xml deployment descriptor.

Example 19-3 The Annotation-Scanning Element

<annotation-scanning>
    <jars>
      <jar>Sample.jar</jar>
    </jars>
    <packages>
      <package>com.oracle.sft.samples</package>
    </packages>
    <beanclasses-from-descriptor>true</beanclasses-from-descriptor>
</annotation-scanning>

Overriding Annotations with the SFT.XML Deployment Descriptor

The following examples show the same configuration parameters specified using both the sip.xml deployment descriptor and using annotations within the Java class file SampleBean. The configuration parameters in the sft.xml deployment descriptor always override the parameters specified using the @ServiceAttributes annotation in a bean's Java class file.

Example 19-4 shows a sft.xml deployment descriptor whose configuration parameters would override the parameters specified using the @ServiceAttributes annotation in the SampleBean Java code shown in Example 19-5.

Example 19-4 SFT.XML for SampleBean

<?xml version="1.0" encoding="UTF-8"?>
<sft-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.oracle.com/sdp/sft/sft.xsd"
    xmlns="http://www.oracle.com/sdp/sft">
  
  <communication-bean>
    <name>SampleBean</name>
    <class-name>com.oracle.sft.samples.SampleBean</class-name>
    <type>Conversation</type>
    <event communication-type="Conversation" event-type="ParticipantEvent.Type.JOINING">
      <orchestration priority="2" />        
    </event>
  </communication-bean>
 
  <service-attributes>
    <registrar>10.182.99.70</registrar>
    <domain-proxy>10.182.99.70</domain-proxy>
    <domain-name>oracle.com</domain-name>
    <xcap-root>sample</xcap-root>
    <mscontrol-jndi-name>mscontrol.ocmp</mscontrol-jndi-name>
    <enableChangeBandwidth>true</enableChangeBandwidth>
    <sdpBandwidthAttributes>
      <totalBandwidth>0</totalBandwidth>
      <bandwidthForActiveDataSenders>800</bandwidthForActiveDataSenders>
      <bandwidthForActiveDataSenders>800</bandwidthForActiveDataSenders>
    </sdpBandwidthAttributes>
    <conferenceEventConfig>
      <minExpirationTime>100</minExpirationTime>
      <defaultExpirationTime>1800</defaultExpirationTime>
      <maxExpirationTime>3600</maxExpirationTime>
      <maxNumOfSubscriptions>100</maxNumOfSubscriptions>
    </conferenceEventConfig>
    <messageObservationEventConfig>
      <minExpirationTime>100</minExpirationTime>
      <defaultExpirationTime>1800</defaultExpirationTime>
      <maxExpirationTime>3600</maxExpirationTime>
      <maxNumOfSubscriptions>100</maxNumOfSubscriptions>
    </messageObservationEventConfig>
    <referEventConfig>1800</referEventConfig>
    <terminatingOperator>tester</terminatingOperator>
    <chargingCollectionFunction>
      <ccf>10.182.99.71</ccf>
      <ccf>10.182.99.72</ccf>
    </chargingCollectionFunction>
    <eventChargingFunction>
      <ecf>10.182.99.71</ecf>
    </eventChargingFunction>
    <statusCode4InitiateEarlyMedia>183</statusCode4InitiateEarlyMedia>    <restAuthorizationAdapter>PRINCIPAL_MATCHING</restAuthorizationAdapter>    <allowedModules></allowedModules>
  </service-attributes>  
 
  <annotation-scanning>
    <jars>
      <jar>Sample.jar</jar>
    </jars>
    <packages>
      <package>com.oracle.sft.samples</package>
    </packages>
    <beanclasses-from-descriptor>true</beanclasses-from-descriptor>
  </annotation-scanning>
</sft-app>

Example 19-5 illustrate the use of the @ServiceAttributes annotation in the SampleBean Java class.

Example 19-5 Code for SampleBean with @ServiceAttributes Annotation

package com.oracle.sft.samples;
 
import com.oracle.sft.api.bean.ParticipantEvent;
import com.oracle.sft.api.bean.ServiceAttributes;
import com.oracle.sft.api.bean.CommunicationBean;
import com.oracle.sft.api.Context;
import com.oracle.sft.api.CommunicationSession;
import com.oracle.sft.api.CommunicationContext;
import com.oracle.sft.api.Communication;
import com.oracle.sft.api.Conversation;
import com.oracle.sft.api.Participant;
import com.oracle.sft.api.Message;
import com.oracle.sft.api.CommunicationService;
 
@ServiceAttributes(
    registrar = "10.182.99.70",
    domainProxy = "10.182.99.70",
    domainName = "oracle.com",
    xcapRoot = "sample",
    mscontrolJndiName = "mscontrol.ocmp",
    enableChangeBandwidth = true,
    sdpBandwidthAttributes = { 0, 800, 800 },
    conferenceEventConfig = { 100, 1800, 3600, 100 },
    messageObservationEventConfig = { 100, 1800, 3600, 100 },
    referEventConfig = 1800,
    terminatingOperator = "tester",
    chargingCollectionFunction = {"10.182.99.71", "10.182.99.72" },    
    eventChargingFunction = { "10.182.99.73" },
    statusCode4InitiateEarlyMedia = 183,
    restAuthorizationAdapter = "PRINCIPAL_MATCHING",
    allowedModules = ""
    )
@CommunicationBean(name = "SampleBean")
public class SampleBean {
  @Context CommunicationSession session;
  @Context CommunicationContext<Communication, Participant, Message> context;
  @Context CommunicationService service;
  
  @ParticipantEvent(type = ParticipantEvent.Type.JOINING,
      communicationType=Conversation.class)
  public void handleJoining() {
    System.out.println(context.getParticipant().getName()  + " joining");
  }
}

SFT.XML Schema

Example 19-6 shows the sft.xml deployment descriptor schema.

Example 19-6 SFT.XML Deployment Descriptor Schema

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           targetNamespace="http://www.oracle.com/sdp/sft"
           xmlns="http://www.oracle.com/sdp/sft"
           elementFormDefault="qualified">
    <xs:element name="orchestrator-class-name" type="xs:token" />
 
    <xs:simpleType name="event-type-def">
        <xs:restriction base="xs:token">
        </xs:restriction>
    </xs:simpleType>
<xs:simpleType name="bandwidth">  
        <xs:restriction base="xs:int">  
            <xs:minInclusive value="0"/>  
        </xs:restriction>  
    </xs:simpleType>  
        
<xs:complexType name="sdpBandwidthAttributes-type-def">
        <xs:sequence>
<xs:element name="totalBandwidth" type="bandwidth" minOccurs="0" maxOccurs="1" />
<xs:element name="bandwidthForActiveDataSenders" type="bandwidth" minOccurs="0" maxOccurs="1" />
<xs:element name="bandwidthForOtherParticipants" type="bandwidth" minOccurs="0" maxOccurs="1" />
        </xs:sequence>
        </xs:complexType>
 
        <xs:complexType name="eventConfig-type-def">
        <xs:sequence>
                        <xs:element name="minExpirationTime" type="xs:nonNegativeInteger" minOccurs="0" maxOccurs="1" />
                        <xs:element name="defaultExpirationTime" type="xs:nonNegativeInteger" minOccurs="0" maxOccurs="1" />
                        <xs:element name="maxExpirationTime" type="xs:nonNegativeInteger" minOccurs="0" maxOccurs="1" />
                        <xs:element name="maxNumOfSubscriptions" type="xs:nonNegativeInteger" minOccurs="0" maxOccurs="1" />
        </xs:sequence>
        </xs:complexType>
 
        <xs:complexType name="ccfs-type-def">
        <xs:sequence>
                        <xs:element name="ccf" type="xs:token" minOccurs="0" maxOccurs="unbounded" />
        </xs:sequence>
        </xs:complexType>
 
        <xs:complexType name="ecfs-type-def">
        <xs:sequence>
                        <xs:element name="ecf" type="xs:token" minOccurs="0" maxOccurs="unbounded" />
        </xs:sequence>
        </xs:complexType>
 
        <xs:element name="orchestration">
        <xs:complexType>
            <xs:attribute name="priority" type="xs:nonNegativeInteger" default="100"/>
        </xs:complexType>
    </xs:element>
 
    <xs:element name="event">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="orchestration" />
            </xs:sequence>
            <xs:attribute name="communication-type" type="xs:token" />
            <xs:attribute name="event-type" type="event-type-def" />
        </xs:complexType>
    </xs:element>
 
    <xs:element name="communication-bean">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="name" type="xs:token" minOccurs="0" />
                <xs:element name="class-name" type="xs:token" />
                <xs:element name="type" type="xs:token" minOccurs="0" />
                <xs:element ref="event" maxOccurs="unbounded" />
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    
    <xs:element name="service-attributes">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="registrar" type="xs:token" minOccurs="0" />
                <xs:element name="domain-proxy" type="xs:token" minOccurs="0" />
                <xs:element name="domain-name" type="xs:token" minOccurs="0" />
                <xs:element name="xcap-root" type="xs:token" minOccurs="0" />
                <xs:element name="mscontrol-jndi-name" type="xs:token" minOccurs="0" />
                <xs:element name="enableChangeBandwidth" type="xs:boolean" default="true" minOccurs="0" maxOccurs="1" />
                <xs:element name="sdpBandwidthAttributes" type="sdpBandwidthAttributes-type-def" minOccurs="0" maxOccurs="1" />
                <xs:element name="conferenceEventConfig" type="eventConfig-type-def" minOccurs="0" maxOccurs="1" />
                <xs:element name="messageObservationEventConfig" type="eventConfig-type-def" minOccurs="0" maxOccurs="1" />
                <xs:element name="referEventConfig" type="xs:nonNegativeInteger" minOccurs="0" maxOccurs="1" />
                <xs:element name="terminatingOperator" type="xs:token" minOccurs="0" maxOccurs="1" />
                <xs:element name="chargingCollectionFunction" type="ccfs-type-def" minOccurs="0" maxOccurs="1" />
                <xs:element name="eventChargingFunction" type="ecfs-type-def" minOccurs="0" maxOccurs="1" />
                <xs:element name="statusCode4InitiateEarlyMedia" type="xs:int" default="183" minOccurs="0" maxOccurs="1" />
                <xs:element name="restAuthorizationAdapter" type="xs:token" minOccurs="0" />
                <xs:element name="allowedModules" type="xs:token" minOccurs="0" />
            </xs:sequence>
        </xs:complexType>
    </xs:element>
 
    <xs:element name="packages">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="package" type="xs:token" minOccurs="0" maxOccurs="unbounded" />
            </xs:sequence>
        </xs:complexType>
    </xs:element>
 
 
    <xs:element name="jars">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="jar" type="xs:token" minOccurs="0" maxOccurs="unbounded" />
            </xs:sequence>
        </xs:complexType>
    </xs:element>
 
    <xs:element name="annotation-scanning">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="jars" minOccurs="0" />
                <xs:element ref="packages" minOccurs="0" />
            </xs:sequence>
            <xs:attribute name="beanclasses-from-descriptor" type="xs:boolean">
                  <xs:annotation>
                    <xs:documentation>
 
                      Only communication beans listed in sft.xml will be
                      processed for further annotation scanning if this attribute is
                      set to "true".
 
                    </xs:documentation>
                  </xs:annotation>
                </xs:attribute>
        </xs:complexType>
    </xs:element>
 
    <xs:element name="sft-app">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="service-attributes" minOccurs="0" />
                <xs:element ref="communication-bean" minOccurs="0" maxOccurs="unbounded" />
                <xs:element ref="annotation-scanning" minOccurs="0" />
            </xs:sequence>
        </xs:complexType>
    </xs:element>
 
</xs:schema>