Page History

h2. SIP Component

*Available as of Camel 2.5*

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 or Stream Control Transmission Protocol (SCTP). SCTP is not supported by the Jain SIP implementation.

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|http://www.ietf.org/rfc/rfc3903.txt]

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:
{code:xml}
<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>
{code}

h3. URI format

The URI scheme for a netty component is as follows

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

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

You can append query options to the URI in the following format, {{?option=value&option=value&...}}

h3. Options

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

{div:class=confluenceTableSmall}
|| Name || Default Value || Description ||
| {{keepAlivestackName}} | {{trueNAME_NOT_SET}} | SettingName of tothe ensureSIP socketStack isinstance notassociated closedwith duean toSIP inactivityEndpoint. |
| {{tcpNoDelaytransport}} | {{truetcp}} | Setting tofor improvechoice TCPof protocoltransport performance |
| {{broadcast}} | {{false}} | Setting to choose Multicast over UDP potocol. Valid choices are "tcp" or "udp". |
| {{connectTimeoutfromUser}} | {{10000}} | Time to wait for a socket connection to be available. Value is in millis.Username of the message originator. *Mandatory setting unless a registry based custom FromHeader is specified.* |
| {{timeoutfromHost}} | {{30000}} | TimeHostname toof waitthe formessage aoriginator. response*Mandatory tosetting beunless receiveda onregistry abased connection.FromHeader Value is inspecified* millis. |
| {{reuseAddressfromPort}} | {{true}} | Setting to facilitate socket multiplexing Port of the message originator. *Mandatory setting unless a registry based FromHeader is specified* |
| {{synctoUser}} | {{true}} | Setting to set endpoint as one-way or request-response Username of the message receiver. *Mandatory setting unless a registry based custom ToHeader is specified.* |
| {{ssltoHost}} | {{false}} | SettingHostname toof specifythe whethermessage SSLreceiver. encryption*Mandatory issetting appliedunless toa thisregistry endpoint based ToHeader is specified* |
| {{sendBufferSizetoPort}} | {{65536 bytes}} | The TCP/UDP buffer sizes to be used during outbound communication. Size is bytes. | Portname of the message receiver. *Mandatory setting unless a registry based ToHeader is specified* |
| {{receiveBufferSizemaxMessageSize}} | {{65536 bytes1048576}} | TheSetting TCP/UDPfor buffermaximum sizesallowed toMessage besize usedin during inbound communication. Size is bytes. |bytes. |
| {{corePoolSizecacheConnections}} | {{10false}} | The number of allocated threads at component startup. Defaults to 10 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. |
| {{maxPoolSizeconsumer}} | {{100false}} | TheThis maximum number of threads that may be allocated to this endpoint. Defaults to 100 setting is used to determine whether the kind of header (FromHeader,ToHeader etc) that needs to be created for this endpoint|
| {{disconnectautomaticDialogSupport}} | {{falseoff}} | WhetherSetting to orspecify notwhether to disconnect(close) from Netty Channel right after use. Can be used for both consumer and producer. |
| {{lazyChannelCreationevery communication should be associated with a dialog. |
| {{contentType}} | {{truetext}} | Setting Channelsfor contentType can be lazilyset created to avoidany exceptions, if the remote server is not up and running when the Camel producer is startedvalid MimeType. |
| {{transferExchangecontentSubType}} | {{falsexml}} | Only used for TCP. You can transfer the exchange over the wire instead of just the body. The following fields are transferred: In body, Out body, fault body, In headers, Out headers, fault headers, exchange properties, exchange exception. This requires that the objects are serializable. Camel will exclude any non-serializable objects and log it at WARN level. |
| {{disconnectOnNoReply}} | {{true}} | If sync is enabled then this option dictates NettyConsumer if it should disconnect where there is no reply to send back. |
| {{noReplyLogLevel}} | {{WARN}} | If sync is enabled this option dictates NettyConsumer which logging level to use when logging a there is no reply to send back. Values are: {{FATAL, ERROR, INFO, DEBUG, OFF}}. |
| {{allowDefaultCodec}} | {{true}} | *Camel 2.4:* The netty component installs a default codec if both, encoder/deocder is null and textline is false. Setting allowDefaultCodec to false prevents the netty component from installing a default codec as the first element in the filter chainSetting for contentSubType can be set to any valid MimeSubType. |
| {{textline}} | {{false}} | *Camel 2.4:* Only used for TCP. If no codec is specified, you can use this flag to indicate a text line based codec; if not specified or the value is false, then Object Serialization is assumed over TCP. receiveTimeoutMillis}} | {{10000}} | Setting for specifying amount of time to wait for a Response and/or Acknowledgement can be received from another SIP stack |
| {{delimiteruseRouterForAllUris}} | {{LINEfalse}} | *Camel 2.4:* The delimiter to use for the textline codec. Possible values are {{LINE}} and {{NULL}}This setting is used when requests are sent to the Presence Agent via a proxy. |
| {{decoderMaxLineLengthmsgExpiration}} | {{10243600}} | *Camel 2.4:* The max line length to use for the textline codec.The amount of time a message received at an endpoint is considered valid |
| {{autoAppendDelimiterpresenceAgent}} | {{truefalse}} | *Camel 2.4:* Whether or not to auto append missing end delimiter when sending using the textline codec. |
| {{encoding}} | {{null}} | *Camel 2.4:* The encoding (a charset name) to use for the textline codec. If not provided, Camel will use the JVM default CharsetThis setting is used to distingish between a Presence Agent & 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. |
{div}

h3. Registry based Options

Codec Handlers and SSL KeystoresSIP requires a number of headers to be sent/received as part of a request. These SIP header can be enlisted in the [Registry], such as in the Spring XML file.

The values that could be passed in, are the following:

{div:class=confluenceTableSmall}
|| Name || Description ||
| {{passphrase}} | password setting to use in order to encrypt/decrypt payloads sent using SSH |
| {{keyStoreFormat}} | keystore format to be used for payload encryption. Defaults to "JKS" if not set |
| {{securityProvider}} | Security provider to be used for payload encryption. Defaults to "SunX509" if not set. |
| {{keyStoreFile}} | Client side certificate keystore to be used for encryption |
| {{trustStoreFile}} | Server side certificate keystore to be used for encryption |
| {{sslHandler}} | Reference to a class that could be used to return an SSL Handler |
| {{encoder}} | A custom Handler class that can be used to perform special marshalling of outbound payloads. Must override {{org.jboss.netty.channel.ChannelDownStreamHandler}}. |
| {{encorders}} | A list of encoder to be used. You can use a String which have values separated by comma, and have the values be looked up in the [Registry]. Just remember to prefix the value with # so Camel knows it should lookup. |
| {{decoder}} | A custom Handler class that can be used to perform special marshalling of inbound payloads. Must override {{org.jboss.netty.channel.ChannelUpStreamHandler}}. |
| {{decoders}} | A list of decorder to be used. You can use a String which have values separated by comma, and have the values be looked up in the [Registry]. Just remember to prefix the value with # so Camel knows it should lookup. |
{div}

h3. Sending Messages to/from a Netty endpoint

h4. Netty Producer

In Producer mode, the component provides the ability to send payloads to a socket endpoint
using either TCP or UDP protocols (with optional SSL support).

The producer mode supports both one-way and request-response based operations.

h4. Netty Consumer

In Consumer mode, the component provides the ability to:
- listen on a specified socket using either TCP or UDP protocols (with optional SSL support),
- receive requests on the socket using text/xml, binary and serialized object based payloads and
- send them along on a route as message exchanges.

The consumer mode supports both one-way and request-response based operations.

h3. Usage Samples

h4. A UDP Netty endpoint using Request-Reply and serialized object payload
{code}
RouteBuilder builder = new RouteBuilder() {
  public void configure() {
    from("netty:udp://localhost:5155?sync=true")
      .process(new Processor() {
         public void process(Exchange exchange) throws Exception {
           Poetry poetry = (Poetry) exchange.getIn().getBody();
           poetry.setPoet("Dr. Sarojini Naidu");
           exchange.getOut().setBody(poetry);
         }
       }
    }
};
{code}

h4. A TCP based Netty consumer endpoint using One-way communication
{code}
RouteBuilder builder = new RouteBuilder() {
  public void configure() {
       from("netty:tcp://localhost:5150")
           .to("mock:result");
  }
};
{code}

h4. An SSL/TCP based Netty consumer endpoint using Request-Reply communication
{code}
JndiRegistry registry = new JndiRegistry(createJndiContext());
registry.bind("password", "changeit");
registry.bind("ksf", new File("src/test/resources/keystore.jks"));
registry.bind("tsf", new File("src/test/resources/keystore.jks"));

context.createRegistry(registry);
context.addRoutes(new RouteBuilder() {
  public void configure() {
      String netty_ssl_endpoint =
         "netty:tcp://localhost:5150?sync=true&ssl=true&passphrase=#password"
         + "&keyStoreFile=#ksf&trustStoreFile=#tsf";
      String return_string =
         "When You Go Home, Tell Them Of Us And Say,"
         + "For Your Tomorrow, We Gave Our Today.";

      from(netty_ssl_endpoint)
       .process(new Processor() {
          public void process(Exchange exchange) throws Exception {
            exchange.getOut().setBody(return_string);
          }
       }
  }
});
{code}

h4. Using Multiple Codecs

In certain cases it may be necessary to add chains of encoders and decoders to the netty pipeline. To add multpile codecs to a camel netty endpoint the 'encoders' and 'decoders' uri parameters should be used. Like the 'encoder' and 'decoder' parameters they are used to supply references (to lists of ChannelUpstreamHandlers and ChannelDownstreamHandlers) that should be added to the  pipeline. Note that if encoders is specified then the encoder param will be ignored, similarly for decoders and the decoder param.

The lists of codecs need to be added to the Camel's registry so they can be resolved when the endpoint is created.

{snippet:id=registry-beans|lang=java|url=camel/trunk/components/camel-netty/src/test/java/org/apache/camel/component/netty/MultipleCodecsTest.java}

Spring's native collections support can be used to specify the codec lists in an application context

{snippet:id=registry-beans|lang=xml|url=camel/trunk/components/camel-netty/src/test/resources/org/apache/camel/component/netty/multiple-codecs.xml}

The bean names can then be used in netty endpoint definitions either as a comma separated list or contained in a List e.g.

{snippet:id=routes|lang=java|url=camel/trunk/components/camel-netty/src/test/java/org/apache/camel/component/netty/MultipleCodecsTest.java}

or via spring.

{snippet:id=routes|lang=xml|url=camel/trunk/components/camel-netty/src/test/resources/org/apache/camel/component/netty/multiple-codecs.xml}

h3. Closing Channel When Complete

When acting as a server you sometimes want to close the channel when, for example, a client conversion is finished.
You can do this by simply setting the endpoint option {{disconnect=true}}.

However you can also instruct Camel on a per message basis as follows.
To instruct Camel to close the channel, you should add a header with the key {{CamelNettyCloseChannelWhenComplete}} set to a boolean {{true}} value.
For instance, the example below will close the channel after it has written the bye message back to the client:
{code}
        from("netty:tcp://localhost:8080").process(new Processor() {
            public void process(Exchange exchange) throws Exception {
                String body = exchange.getIn().getBody(String.class);
                exchange.getOut().setBody("Bye " + body);
                // some condition which determines if we should close
                if (close) {
                    exchange.getOut().setHeader(NettyConstants.NETTY_CLOSE_CHANNEL_WHEN_COMPLETE, true);
                }
            }
        });
{code}

h3. Adding custom channel pipeline factories to gain complete control over a created pipeline

*Available as of Camel 2.5*

Custom channel pipelines provide complete control to the user over the handler/interceptor chain by inserting custom handler(s), encoder(s) & decoders without having to specify them in the Netty Endpoint URL in a very simple way.

In order to add a custom pipeline, a custom channel pipeline factory must be created and registered with the context via the context registry (JNDIRegistry,or the camel-spring ApplicationContextRegistry etc).

A custom pipeline factory must be constructed as follows
* A Producer linked channel pipeline factory must extend the abstract class ClientPipelineFactory.
* A Consumer linked channel pipeline factory must extend the abstract class ServerPipelineFactory.
* The classes can optionally override the getPipeline() method in order to insert custom handler(s), encoder(s) and decoder(s). Not overriding the getPipeline() method creates a pipeline with no handlers, encoders or decoders wired to the pipeline.

The example below shows how ServerChannel Pipeline factory may be created
{code}
public class SampleServerChannelPipelineFactory extends ServerPipelineFactory {
    private int maxLineSize = 1024;
    private boolean invoked;

    public ChannelPipeline getPipeline() throws Exception {
        invoked = true;

        ChannelPipeline channelPipeline = Channels.pipeline();

        channelPipeline.addLast("encoder-SD", new StringEncoder(CharsetUtil.UTF_8));
        channelPipeline.addLast("decoder-DELIM", new DelimiterBasedFrameDecoder(maxLineSize, true, Delimiters.lineDelimiter()));
        channelPipeline.addLast("decoder-SD", new StringDecoder(CharsetUtil.UTF_8));
        channelPipeline.addLast("handler", new ServerChannelHandler(consumer));

        return channelPipeline;
    }

    public boolean isfactoryInvoked() {
        return invoked;
    }
}
{code}

The custom channel pipeline factory can then be added to the registry and instantiated/utilized on a camel route in the following way
{code}
Registry registry = camelContext.getRegistry();
serverPipelineFactory = new TestServerChannelPipelineFactory();
registry.bind("spf", serverPipelineFactory);
context.addRoutes(new RouteBuilder() {
  public void configure() {
      String netty_ssl_endpoint =
         "netty:tcp://localhost:5150?serverPipelineFactory=#spf"
      String return_string =
         "When You Go Home, Tell Them Of Us And Say,"
         + "For Your Tomorrow, We Gave Our Today.";

      from(netty_ssl_endpoint)
       .process(new Processor() {
          public void process(Exchange exchange) throws Exception {
            exchange.getOut().setBody(return_string);
          }
       }
  }
});

{code}