| Oracle® Communications Converged Application Server Developer's Guide Release 5.1 Part Number E27707-01 |
|
|
PDF · Mobi · ePub |
| Oracle® Communications Converged Application Server Developer's Guide Release 5.1 Part Number E27707-01 |
|
|
PDF · Mobi · ePub |
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.
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.
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.
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.
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
The following sections describe the elements in the Converged Application Server-specific deployment descriptor sft.xml.
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:
|
|
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:
For example:
|
|
event |
Identifies events pertaining to the type of communication. The possible values are those defined using the following method-level event annotations:
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:
|
|
event-type |
Identifies events pertaining to the type of communication. The possible values are those defined using the ParticipantEvent.Type and CommunicationEvent.Type:
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>
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 |
|---|---|
|
|
The IP address or DNS name of the Registrar to use in conjunction with SFT. |
|
|
The IP address or DNS name of the Domain Proxy to use in conjunction with SFT. |
|
|
Specifies the default domain name, which is appended to all user names. |
|
|
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. |
|
|
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. |
|
|
Specifies whether or not to enable the alternate bandwidth settings specified by the
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. |
|
|
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
For example: <sdpBandwidthAttributes> <totalBandwidth>0</totalBandwidth> <bandwidthForActiveDataSenders>800</bandwidthForActiveDataSenders> <bandwidthForActiveDataSenders>800</bandwidthForActiveDataSenders> </sdpBandwidthAttributes> See "Setting the Communication Hold Bandwidth" for more information. |
|
|
Specifies the configuration parameters for a conference event. Elements you can define within the
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. |
|
|
Specifies the configuration parameters for a message waiting event. Elements you can define within the
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. |
|
|
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> |
|
|
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. |
|
|
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
|
|
|
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
|
|
|
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 can only be specified using 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");
}
}
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>
|
 Copyright © 2005, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|