SIP

Since Camel 2.5

Both producer and consumer are supported

The SIP component in Camel is a communication component, based on the Jain SIP implementation (available under the JCP license).

Session Initiation Protocol (SIP) is an IETF-defined signaling protocol, widely used for controlling multimedia communication sessions such as voice and video calls over Internet Protocol (IP).The SIP protocol is an Application Layer protocol designed to be independent of the underlying transport layer; it can run on Transmission Control Protocol (TCP), User Datagram Protocol (UDP) or Stream Control Transmission Protocol (SCTP).

The Jain SIP implementation supports TCP and UDP only.

The Camel SIP component only supports the SIP Publish and Subscribe capability as described in the RFC3903 - Session Initiation Protocol (SIP) Extension for Event

This camel component supports both producer and consumer endpoints.

Camel SIP Producers (Event Publishers) and SIP Consumers (Event Subscribers) communicate event & state information to each other using an intermediary entity called a SIP Presence Agent (a stateful brokering entity).

For SIP based communication, a SIP Stack with a listener must be instantiated on both the SIP Producer and Consumer (using separate ports if using localhost). This is necessary in order to support the handshakes & acknowledgements exchanged between the SIP Stacks during communication.

Maven users will need to add the following dependency to their pom.xml for this component:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-sip</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>

URI format

The URI scheme for a sip endpoint is as follows:

sip://johndoe@localhost:99999[?options]
sips://johndoe@localhost:99999/[?options]

This component supports producer and consumer endpoints for both TCP and UDP.

The SIP Component offers an extensive set of configuration options & capability to create custom stateful headers needed to propagate state via the SIP protocol.

Configuring Options

Camel components are configured on two separate levels:

  • component level

  • endpoint level

Configuring Component Options

The component level is the highest level which holds general and common configurations that are inherited by the endpoints. For example a component may have security settings, credentials for authentication, urls for network connection and so forth.

Some components only have a few options, and others may have many. Because components typically have pre configured defaults that are commonly used, then you may often only need to configure a few options on a component; or none at all.

Configuring components can be done with the Component DSL, in a configuration file (application.properties|yaml), or directly with Java code.

Configuring Endpoint Options

Where you find yourself configuring the most is on endpoints, as endpoints often have many options, which allows you to configure what you need the endpoint to do. The options are also categorized into whether the endpoint is used as consumer (from) or as a producer (to), or used for both.

Configuring endpoints is most often done directly in the endpoint URI as path and query parameters. You can also use the Endpoint DSL as a type safe way of configuring endpoints.

A good practice when configuring options is to use Property Placeholders, which allows to not hardcode urls, port numbers, sensitive information, and other settings. In other words placeholders allows to externalize the configuration from your code, and gives more flexibility and reuse.

The following two sections lists all the options, firstly for the component followed by the endpoint.

Component Options

The SIP component supports 3 options, which are listed below.

Name Description Default Type

bridgeErrorHandler (consumer)

Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored.

false

boolean

lazyStartProducer (producer)

Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing.

false

boolean

autowiredEnabled (advanced)

Whether autowiring is enabled. This is used for automatic autowiring options (the option must be marked as autowired) by looking up in the registry to find if there is a single instance of matching type, which then gets configured on the component. This can be used for automatic configuring JDBC data sources, JMS connection factories, AWS Clients, etc.

true

boolean

Endpoint Options

The SIP endpoint is configured using URI syntax:

sip:uri

with the following path and query parameters:

Path Parameters (1 parameters)

Name Description Default Type

uri (common)

Required URI of the SIP server to connect to (the username and password can be included such as: john:secretmyserver:9999).

URI

Query Parameters (44 parameters)

Name Description Default Type

cacheConnections (common)

Should connections be cached by the SipStack to reduce cost of connection creation. This is useful if the connection is used for long running conversations.

false

boolean

contentSubType (common)

Setting for contentSubType can be set to any valid MimeSubType.

plain

String

contentType (common)

Setting for contentType can be set to any valid MimeType.

text

String

eventHeaderName (common)

Setting for a String based event type.

String

eventId (common)

Setting for a String based event Id. Mandatory setting unless a registry based FromHeader is specified.

String

fromHost (common)

Hostname of the message originator. Mandatory setting unless a registry based FromHeader is specified.

String

fromPort (common)

Port of the message originator. Mandatory setting unless a registry based FromHeader is specified.

int

fromUser (common)

Username of the message originator. Mandatory setting unless a registry based custom FromHeader is specified.

String

msgExpiration (common)

The amount of time a message received at an endpoint is considered valid.

3600

int

receiveTimeoutMillis (common)

Setting for specifying amount of time to wait for a Response and/or Acknowledgement can be received from another SIP stack.

10000

long

stackName (common)

Name of the SIP Stack instance associated with an SIP Endpoint.

NAME_NOT_SET

String

toHost (common)

Hostname of the message receiver. Mandatory setting unless a registry based ToHeader is specified.

String

toPort (common)

Portname of the message receiver. Mandatory setting unless a registry based ToHeader is specified.

int

toUser (common)

Username of the message receiver. Mandatory setting unless a registry based custom ToHeader is specified.

String

transport (common)

Setting for choice of transport protocol. Valid choices are tcp or udp.

Enum values:

  • tcp

  • udp

tcp

String

bridgeErrorHandler (consumer)

Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored.

false

boolean

consumer (consumer)

This setting is used to determine whether the kind of header (FromHeader,ToHeader etc) that needs to be created for this endpoint.

false

boolean

presenceAgent (consumer)

This setting is used to distinguish between a Presence Agent and a consumer. This is due to the fact that the SIP Camel component ships with a basic Presence Agent (for testing purposes only). Consumers have to set this flag to true.

false

boolean

exceptionHandler (consumer (advanced))

To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this option is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.

ExceptionHandler

exchangePattern (consumer (advanced))

Sets the exchange pattern when the consumer creates an exchange.

Enum values:

  • InOnly

  • InOut

  • InOptionalOut

ExchangePattern

lazyStartProducer (producer)

Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing.

false

boolean

addressFactory (advanced)

To use a custom AddressFactory.

AddressFactory

callIdHeader (advanced)

A custom Header object containing call details. Must implement the type javax.sip.header.CallIdHeader.

CallIdHeader

contactHeader (advanced)

An optional custom Header object containing verbose contact details (email, phone number etc). Must implement the type javax.sip.header.ContactHeader.

ContactHeader

contentTypeHeader (advanced)

A custom Header object containing message content details. Must implement the type javax.sip.header.ContentTypeHeader.

ContentTypeHeader

eventHeader (advanced)

A custom Header object containing event details. Must implement the type javax.sip.header.EventHeader.

EventHeader

expiresHeader (advanced)

A custom Header object containing message expiration details. Must implement the type javax.sip.header.ExpiresHeader.

ExpiresHeader

extensionHeader (advanced)

A custom Header object containing user/application specific details. Must implement the type javax.sip.header.ExtensionHeader.

ExtensionHeader

fromHeader (advanced)

A custom Header object containing message originator settings. Must implement the type javax.sip.header.FromHeader.

FromHeader

headerFactory (advanced)

To use a custom HeaderFactory.

HeaderFactory

listeningPoint (advanced)

To use a custom ListeningPoint implementation.

ListeningPoint

maxForwardsHeader (advanced)

A custom Header object containing details on maximum proxy forwards. This header places a limit on the viaHeaders possible. Must implement the type javax.sip.header.MaxForwardsHeader.

MaxForwardsHeader

maxMessageSize (advanced)

Setting for maximum allowed Message size in bytes.

1048576

int

messageFactory (advanced)

To use a custom MessageFactory.

MessageFactory

sipFactory (advanced)

To use a custom SipFactory to create the SipStack to be used.

SipFactory

sipStack (advanced)

To use a custom SipStack.

SipStack

sipUri (advanced)

To use a custom SipURI. If none configured, then the SipUri fallback to use the options toUser toHost:toPort.

SipURI

toHeader (advanced)

A custom Header object containing message receiver settings. Must implement the type javax.sip.header.ToHeader.

ToHeader

viaHeaders (advanced)

List of custom Header objects of the type javax.sip.header.ViaHeader. Each ViaHeader containing a proxy address for request forwarding. (Note this header is automatically updated by each proxy when the request arrives at its listener).

List

implementationDebugLogFile (logging)

Name of client debug log file to use for logging.

String

implementationServerLogFile (logging)

Name of server log file to use for logging.

String

implementationTraceLevel (logging)

Logging level for tracing.

0

String

maxForwards (proxy)

Number of maximum proxy forwards.

int

useRouterForAllUris (proxy)

This setting is used when requests are sent to the Presence Agent via a proxy.

false

boolean

Sending Messages to/from a SIP endpoint

Creating a Camel SIP Publisher

In the example below, a SIP Publisher is created to send SIP Event publications to
a user "agent@localhost:5152". This is the address of the SIP Presence Agent which acts as a broker between the SIP Publisher and Subscriber

  • using a SIP Stack named client

  • using a registry based eventHeader called evtHdrName

  • using a registry based eventId called evtId

  • from a SIP Stack with Listener set up as user2@localhost:3534

  • The Event being published is EVENT_A

  • A Mandatory Header called REQUEST_METHOD is set to Request.Publish thereby setting up the endpoint as a Event publisher"

producerTemplate.sendBodyAndHeader(
    "sip://agent@localhost:5152?stackName=client&eventHeaderName=evtHdrName&eventId=evtid&fromUser=user2&fromHost=localhost&fromPort=3534",
    "EVENT_A",
    "REQUEST_METHOD",
    Request.PUBLISH);

Creating a Camel SIP Subscriber

In the example below, a SIP Subscriber is created to receive SIP Event publications sent to
a user "johndoe@localhost:5154"

  • using a SIP Stack named Subscriber

  • registering with a Presence Agent user called agent@localhost:5152

  • using a registry based eventHeader called evtHdrName. The evtHdrName contains the Event which is se to "Event_A"

  • using a registry based eventId called evtId

@Override
protected RouteBuilder createRouteBuilder() throws Exception {
    return new RouteBuilder() {
        @Override
        public void configure() throws Exception {
            // Create PresenceAgent
            from("sip://agent@localhost:5152?stackName=PresenceAgent&presenceAgent=true&eventHeaderName=evtHdrName&eventId=evtid")
                .to("mock:neverland");

            // Create Sip Consumer(Event Subscriber)
            from("sip://johndoe@localhost:5154?stackName=Subscriber&toUser=agent&toHost=localhost&toPort=5152&eventHeaderName=evtHdrName&eventId=evtid")
                .to("log:ReceivedEvent?level=DEBUG")
                .to("mock:notification");

        }
    };
}

The Camel SIP component also ships with a Presence Agent that is meant to be used for Testing and Demo purposes only. An example of instantiating a Presence Agent is given above.

Note that the Presence Agent is set up as a user agent@localhost:5152 and is capable of communicating with both Publisher as well as Subscriber. It has a separate SIP stackName distinct from Publisher as well as Subscriber. While it is set up as a Camel Consumer, it does not actually send any messages along the route to the endpoint "mock:neverland".

Spring Boot Auto-Configuration

When using sip with Spring Boot make sure to use the following Maven dependency to have support for auto configuration:

<dependency>
  <groupId>org.apache.camel.springboot</groupId>
  <artifactId>camel-sip-starter</artifactId>
  <version>x.x.x</version>
  <!-- use the same version as your Camel core version -->
</dependency>

The component supports 4 options, which are listed below.

Name Description Default Type

camel.component.sip.autowired-enabled

Whether autowiring is enabled. This is used for automatic autowiring options (the option must be marked as autowired) by looking up in the registry to find if there is a single instance of matching type, which then gets configured on the component. This can be used for automatic configuring JDBC data sources, JMS connection factories, AWS Clients, etc.

true

Boolean

camel.component.sip.bridge-error-handler

Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored.

false

Boolean

camel.component.sip.enabled

Whether to enable auto configuration of the sip component. This is enabled by default.

Boolean

camel.component.sip.lazy-start-producer

Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing.

false

Boolean
Back to top