Repository: camel Updated Branches: refs/heads/master 9f916346a -> e8b27bfcb
Added camel-sip docs to Gitbook Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/e8b27bfc Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/e8b27bfc Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/e8b27bfc Branch: refs/heads/master Commit: e8b27bfcb27ca2d0a4e29ced62f21ee966ab851b Parents: 9f91634 Author: Andrea Cosentino <anco...@gmail.com> Authored: Thu May 26 16:51:21 2016 +0200 Committer: Andrea Cosentino <anco...@gmail.com> Committed: Thu May 26 16:51:21 2016 +0200 ---------------------------------------------------------------------- components/camel-sip/src/main/docs/sip.adoc | 213 +++++++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 2 files changed, 214 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/e8b27bfc/components/camel-sip/src/main/docs/sip.adoc ---------------------------------------------------------------------- diff --git a/components/camel-sip/src/main/docs/sip.adoc b/components/camel-sip/src/main/docs/sip.adoc new file mode 100644 index 0000000..b7f9a1f --- /dev/null +++ b/components/camel-sip/src/main/docs/sip.adoc @@ -0,0 +1,213 @@ +[[Sip-SIPComponent]] +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 (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 +http://www.ietf.org/rfc/rfc3903.txt[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: + +[source,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> +------------------------------------------------------------ + +[[Sip-URIformat]] +URI format +^^^^^^^^^^ + +The URI scheme for a sip endpoint is as follows: + +[source,java] +----------------------------------------- +sip://johndoe@localhost:99999[?options] +sips://johndoe@localhost:99999/[?options] +----------------------------------------- + +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&...` + +[[Sip-Options]] +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. + + +// component options: START +The SIP component has no options. +// component options: END + + + +// endpoint options: START +The SIP component supports 45 endpoint options which are listed below: + +{% raw %} +[width="100%",cols="2s,1,1m,1m,5",options="header"] +|======================================================================= +| Name | Group | Default | Java Type | Description +| uri | common | | URI | *Required* URI of the SIP server to connect to (the username and password can be included such as: john:secretmyserver:9999) +| cacheConnections | common | false | boolean | 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. +| contentSubType | common | plain | String | Setting for contentSubType can be set to any valid MimeSubType. +| contentType | common | text | String | Setting for contentType can be set to any valid MimeType. +| eventHeaderName | common | | String | Setting for a String based event type. +| eventId | common | | String | Setting for a String based event Id. Mandatory setting unless a registry based FromHeader is specified +| fromHost | common | | String | Hostname of the message originator. Mandatory setting unless a registry based FromHeader is specified +| fromPort | common | | int | Port of the message originator. Mandatory setting unless a registry based FromHeader is specified +| fromUser | common | | String | Username of the message originator. Mandatory setting unless a registry based custom FromHeader is specified. +| msgExpiration | common | 3600 | int | The amount of time a message received at an endpoint is considered valid +| receiveTimeoutMillis | common | 10000 | long | Setting for specifying amount of time to wait for a Response and/or Acknowledgement can be received from another SIP stack +| stackName | common | NAME_NOT_SET | String | Name of the SIP Stack instance associated with an SIP Endpoint. +| toHost | common | | String | Hostname of the message receiver. Mandatory setting unless a registry based ToHeader is specified +| toPort | common | | int | Portname of the message receiver. Mandatory setting unless a registry based ToHeader is specified +| toUser | common | | String | Username of the message receiver. Mandatory setting unless a registry based custom ToHeader is specified. +| transport | common | tcp | String | Setting for choice of transport protocol. Valid choices are tcp or udp. +| bridgeErrorHandler | consumer | false | boolean | 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/ERROR level and ignored. +| consumer | consumer | false | boolean | This setting is used to determine whether the kind of header (FromHeaderToHeader etc) that needs to be created for this endpoint +| presenceAgent | consumer | false | boolean | This setting is used to distinguish 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. +| exceptionHandler | consumer (advanced) | | ExceptionHandler | To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions that will be logged at WARN/ERROR level and ignored. +| addressFactory | advanced | | AddressFactory | To use a custom AddressFactory +| callIdHeader | advanced | | CallIdHeader | A custom Header object containing call details. Must implement the type javax.sip.header.CallIdHeader +| contactHeader | advanced | | ContactHeader | An optional custom Header object containing verbose contact details (email phone number etc). Must implement the type javax.sip.header.ContactHeader +| contentTypeHeader | advanced | | ContentTypeHeader | A custom Header object containing message content details. Must implement the type javax.sip.header.ContentTypeHeader +| eventHeader | advanced | | EventHeader | A custom Header object containing event details. Must implement the type javax.sip.header.EventHeader +| exchangePattern | advanced | InOnly | ExchangePattern | Sets the default exchange pattern when creating an exchange +| expiresHeader | advanced | | ExpiresHeader | A custom Header object containing message expiration details. Must implement the type javax.sip.header.ExpiresHeader +| extensionHeader | advanced | | ExtensionHeader | A custom Header object containing user/application specific details. Must implement the type javax.sip.header.ExtensionHeader +| fromHeader | advanced | | FromHeader | A custom Header object containing message originator settings. Must implement the type javax.sip.header.FromHeader +| headerFactory | advanced | | HeaderFactory | To use a custom HeaderFactory +| listeningPoint | advanced | | ListeningPoint | To use a custom ListeningPoint implementation +| maxForwardsHeader | advanced | | MaxForwardsHeader | 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 +| maxMessageSize | advanced | 1048576 | int | Setting for maximum allowed Message size in bytes. +| messageFactory | advanced | | MessageFactory | To use a custom MessageFactory +| sipFactory | advanced | | SipFactory | To use a custom SipFactory to create the SipStack to be used +| sipStack | advanced | | SipStack | To use a custom SipStack +| sipUri | advanced | | SipURI | To use a custom SipURI. If none configured then the SipUri fallback to use the options toUser toHost:toPort +| synchronous | advanced | false | boolean | Sets whether synchronous processing should be strictly used or Camel is allowed to use asynchronous processing (if supported). +| toHeader | advanced | | ToHeader | A custom Header object containing message receiver settings. Must implement the type javax.sip.header.ToHeader +| viaHeaders | advanced | | List | 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) +| implementationDebugLogFile | logging | | String | Name of client debug log file to use for logging +| implementationServerLogFile | logging | | String | Name of server log file to use for logging +| implementationTraceLevel | logging | 0 | String | Logging level for tracing +| maxForwards | proxy | | int | Number of maximum proxy forwards +| useRouterForAllUris | proxy | false | boolean | This setting is used when requests are sent to the Presence Agent via a proxy. +|======================================================================= +{% endraw %} +// endpoint options: END + +[[Sip-SendingMessagestofromaSIPendpoint]] +Sending Messages to/from a SIP endpoint +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +[[Sip-CreatingaCamelSIPPublisher]] +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" + +[source,java] +---------------------------------------------------------------------------------------------------------------------------------------------- +producerTemplate.sendBodyAndHeader( + "sip://agent@localhost:5152?stackName=client&eventHeaderName=evtHdrName&eventId=evtid&fromUser=user2&fromHost=localhost&fromPort=3534", + "EVENT_A", + "REQUEST_METHOD", + Request.PUBLISH); +---------------------------------------------------------------------------------------------------------------------------------------------- + +[[Sip-CreatingaCamelSIPSubscriber]] +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 + +[source,java] +---------------------------------------------------------------------------------------------------------------------------------------------------------- +@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". http://git-wip-us.apache.org/repos/asf/camel/blob/e8b27bfc/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index d1f0fdd..3808fe8 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -235,6 +235,7 @@ * [Servlet](servlet.adoc) * [Servlet Listener](servletlistener.adoc) * [Shiro](shiro-security.adoc) + * [SIP](sip.adoc) * [SJMS](sjms.adoc) * [SJMS Batch](sjms-batch.adoc) * [Telegram](telegram.adoc)
