SipMessage.Builder (SIP Framer and Parser Library 2.0.1 API)

All Known Subinterfaces:

SipRequest.Builder, SipResponse.Builder

All Known Implementing Classes:

SipMessageBuilder, SipRequestBuilder, SipResponseBuilder

Enclosing interface:

SipMessage
```
public static interface SipMessage.Builder<T extends SipMessage>
```
Whenever you create a new SipMessage you will end up with a SipMessage.Builder. The pattern of the SipMessage builders is that you can specify the various headers, request-uri, body etc through the withXXX-methods and then upon build time, the builder will call out to any registered functions (as registered through the onXXX-methods) allowing the application to make any last minute changes. In a real SIP stack there are headers within a SipMessage that typically needs to be manipulated before being sent out over the network. One such header is the ViaHeader where the transport layer typically has the responsibility to fill out the ip and port from which the message was sent as well as specify the transport used. The idea is as follows: everything within this SIP library is immutable, which includes SipRequest and SipResponses but if you build a stack, the stack may actually need to change headers before creating the "final" version of the SipMessage which is then sent out over the network. The typical use case is of course the ViaHeader where it typically isn't known by the application which protocol, or interface of the stack will be used. This is only known at the time the message is about to be sent out and will (should) be filled out by the transport layer. Therefore, if you build a stack you probably want to pass down a SipMessage.Builder to be "sent" all the way down to the transport layer which will All callback as registered through the various onXXXX-methods allow for multiple callbacks to be registered. They are called in reverse order from the order of registration. TODO: don't think I will do this anymore. If you add the same header via an of the three methods then TODO: that header will be included three times. I.e., if you call withHeaderBuilder and withHeader and TODO: the same header also exists in the template then it will be included that many times. Order of precedence where the top one "wins" over the others:
- Any header added as a builder object will ALWAYS take precedence
- Any header added through a withXXX-method
- Any header copied from a "template"
I.e., if you e.g. have added a from-header builder object through Builder#withFromHeader(AddressParametersHeader.Builder) method then that builder will be used even if this builder is based off another SipMessage (which then serves as a "template") TODO: add and/or clarify how headers are treated in general, i.e.: A header can be added to the final SipMessage that is being built via 1 out of 3 ways:
- Either via explicitly calling withXXXBuilder to add a builder object for that header
- Or by explicitly calling withXXXHeader
- Or by copying an existing header from the SipMessage we are using as a template for constructing this new sip message.
No matter how a header is added to the final message (via one of the three ways described above) you will be given the opportunity to change the value of the header by registering a function for manipulating the header just before it gets added. You do so through two methods:
- onHeader(Function)
- or io.pkts.packet.sip.SipMessage.Builder#onHeaderBuilder(Consumer)
The first method is called when a header was added without a builder already created from it, which is the case when a header is copied from the template or when you called onXXXHeader(header). The reason for this is unless you actually want to change it, we don't want to waste time on constructing a builder that you are not going to use. However, if you added the header as a builder object then we will of coruse use that builder.

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`T`	`build()`
`default boolean`	`isSipRequestBuilder()`
`default boolean`	`isSipResponseBuilder()`
`SipMessage.Builder<T>`	`onCommit(java.util.function.Consumer<SipMessage> f)` After the `SipMessage` has been fully built and created the "end result" will be conveyed to the registered function.
`SipMessage.Builder<T>`	`onContactHeader(java.util.function.Consumer<AddressParametersHeader.Builder<ContactHeader>> f)`
`SipMessage.Builder<T>`	`onCSeqHeader(java.util.function.Consumer<CSeqHeader.Builder> f)`
`SipMessage.Builder<T>`	`onFromHeader(java.util.function.Consumer<AddressParametersHeader.Builder<FromHeader>> f)`
`SipMessage.Builder<T>`	`onHeader(java.util.function.Function<SipHeader,SipHeader> f)` Whenever a header is about to be pushed onto the new `SipMessage` you have a chance to change the value of that header.
`SipMessage.Builder<T>`	`onMaxForwardsHeader(java.util.function.Consumer<MaxForwardsHeader.Builder> f)`
`SipMessage.Builder<T>`	`onRecordRouteHeader(java.util.function.Consumer<AddressParametersHeader.Builder<RecordRouteHeader>> f)` Called when a Record-Route header is processed (except for the top-most one, then `onTopMostRecordRouteHeader(Consumer)` is called instead)
`SipMessage.Builder<T>`	`onRequestURI(java.util.function.Function<SipURI,SipURI> f)`
`SipMessage.Builder<T>`	`onRouteHeader(java.util.function.Consumer<AddressParametersHeader.Builder<RouteHeader>> f)` Called when a Route header is processed (except for the top-most one, then `onTopMostRouteHeader(Consumer)` is called instead)
`SipMessage.Builder<T>`	`onToHeader(java.util.function.Consumer<AddressParametersHeader.Builder<ToHeader>> f)`
`SipMessage.Builder<T>`	`onTopMostRecordRouteHeader(java.util.function.Consumer<AddressParametersHeader.Builder<RecordRouteHeader>> f)` Called when the top-most Record Route header is processed.
`SipMessage.Builder<T>`	`onTopMostRouteHeader(java.util.function.Consumer<AddressParametersHeader.Builder<RouteHeader>> f)` Called when the top-most Route header is processed.
`SipMessage.Builder<T>`	`onTopMostViaHeader(java.util.function.Consumer<ViaHeader.Builder> f)` Called when the top-most Via header is processed.
`SipMessage.Builder<T>`	`onViaHeader(java.util.function.BiConsumer<Integer,ViaHeader.Builder> f)` Called when a Via header is processed and the first argument is the index of the Via being processed.
`default SipMessage.Builder<SipRequest>`	`toSipRequestBuilder()`
`default SipMessage.Builder<SipResponse>`	`toSipResponseBuilder()`
`SipMessage.Builder<T>`	`withBody(Buffer body)`
`SipMessage.Builder<T>`	`withCallIdHeader(CallIdHeader callID)`
`SipMessage.Builder<T>`	`withContactHeader(ContactHeader contact)`
`SipMessage.Builder<T>`	`withCSeqHeader(CSeqHeader cseq)`
`SipMessage.Builder<T>`	`withFromHeader(FromHeader from)` Set the `FromHeader` to be used by the new `SipMessage`.
`SipMessage.Builder<T>`	`withFromHeader(String from)`
`SipMessage.Builder<T>`	`withHeader(SipHeader header)` Adds the header to the list of headers already specified within this builder.
`SipMessage.Builder<T>`	`withHeaders(List<SipHeader> headers)`
`SipMessage.Builder<T>`	`withMaxForwardsHeader(MaxForwardsHeader maxForwards)`
`SipMessage.Builder<T>`	`withNoDefaults()` By default, the following headers will automatically be generated if not explicitly provided (note: there is a slight difference between request/response): `ToHeader` - the request-uri will be used to construct the to-header in the case of a request.
`SipMessage.Builder<T>`	`withNoRoutes()` Sometimes you may want to just wipe out all the potential `RouteHeader`s that e.g.
`SipMessage.Builder<T>`	`withPoppedRoute()` Pop the top-most route.
`SipMessage.Builder<T>`	`withPoppedVia()` Pop the top-most via.
`SipMessage.Builder<T>`	`withPushHeader(SipHeader header)` Push the header to be the first on the list of existing headers already added to this builder.
`SipMessage.Builder<T>`	`withRecordRouteHeader(RecordRouteHeader recordRoute)` Set a Record Router header to be used on the message that is being built.
`SipMessage.Builder<T>`	`withRecordRouteHeaders(List<RecordRouteHeader> recordRoute)`
`SipMessage.Builder<T>`	`withRecordRouteHeaders(RecordRouteHeader... recordRoute)` Set a list of Record Route headers.
`SipMessage.Builder<T>`	`withRouteHeader(RouteHeader route)` Set a Router header to be used on the message that is being built.
`SipMessage.Builder<T>`	`withRouteHeaders(List<RouteHeader> routes)`
`SipMessage.Builder<T>`	`withRouteHeaders(RouteHeader... routes)` Set a list of Route headers.
`SipMessage.Builder<T>`	`withToHeader(String to)`
`SipMessage.Builder<T>`	`withToHeader(ToHeader to)`
`SipMessage.Builder<T>`	`withTopMostRecordRouteHeader(RecordRouteHeader recordRoute)` Push the given Record Route header to the top of the potential list of existing Record Route headers.
`SipMessage.Builder<T>`	`withTopMostRouteHeader(RouteHeader route)` Push the given Route header to the top of the potential list of existing Route headers.
`SipMessage.Builder<T>`	`withTopMostViaHeader()` Typically the `ViaHeader` will have to be filled out by the stack at some later point, which is when the message is about to be sent, so when you create the message you don't have all the details just yet.
`SipMessage.Builder<T>`	`withTopMostViaHeader(ViaHeader via)` Push the given Via header to the top of the potential list of existing Via headers.
`SipMessage.Builder<T>`	`withViaHeader(ViaHeader via)` Add a Via header to be used on the message that is being built.
`SipMessage.Builder<T>`	`withViaHeaders(List<ViaHeader> vias)` Set a list of Via headers.
`SipMessage.Builder<T>`	`withViaHeaders(ViaHeader... vias)` Set a list of Via headers.

- Method Detail
  - isSipRequestBuilder
```
default boolean isSipRequestBuilder()
```
  - isSipResponseBuilder
```
default boolean isSipResponseBuilder()
```
  - toSipRequestBuilder
```
default SipMessage.Builder<SipRequest> toSipRequestBuilder()
```
  - toSipResponseBuilder
```
default SipMessage.Builder<SipResponse> toSipResponseBuilder()
```
  - withNoDefaults
```
SipMessage.Builder<T> withNoDefaults()
```
    By default, the following headers will automatically be generated if not explicitly provided (note: there is a slight difference between request/response):
    - ToHeader - the request-uri will be used to construct the to-header in the case of a request. For a response you have to supply it
    - CSeqHeader - a new CSeq header will be added where the method is the same as this message and the sequence number is set to 1
    - CallIdHeader - a new random call-id will be added
    - MaxForwardsHeader - if we are building a request, a max forwards of 70 will be added
    - ContentLengthHeader - Will be added if there is a body on the message and the length set to the correct length.
    but if you don't want that, simply call this method and all the defaults of this builder will be suspended. Of course, if you wish to actually construct a valid SipMessage you are then responsible for adding the mandatory headers to this builder (unless you don't care of course because perhaps you are building a test tool meant to torture test a SIP server).
    Returns:
  - onHeader
```
SipMessage.Builder<T> onHeader(java.util.function.Function<SipHeader,SipHeader> f)
                        throws IllegalStateException
```
    Whenever a header is about to be pushed onto the new SipMessage you have a chance to change the value of that header. You do so by registering a function that accepts a SipHeader as an argument and that returns a SipHeader, which is the header that will be pushed onto the new SipMessage. If you do not want to include the header, then simply return null and the header will be dropped. If you wish to leave the header un-touched, then simply return it has is. Also note that the following headers have explicit "on" methods (they are considered to be "system" headers):
    The reason is simply because these are typically manipulated before copying them over to a new request or response (e.g., Max Forwards is decremented, CSeq may increase etc) and therefore it makes life easier if those headers are "down casted" to their specific types.
    Parameters:
    
    f -
    
    Returns:
    
    Throws:
    
    IllegalStateException - in case a function already had been registered with this builder.
  - withHeader
```
SipMessage.Builder<T> withHeader(SipHeader header)
```
    Adds the header to the list of headers already specified within this builder. The header will be added last to the list of headers. Any already existing headers with the same name will be preserved as is. If there are any headers with the same name as part of the SipMessage used as a template, then those headers will TODO: this is essentially an "add header" so should it be called that? TODO: and then should there be a set version? Just goes bad with a fluent TODO: naming.
    
    Parameters:
    
    header -
    
    Returns:
  - withHeaders
```
SipMessage.Builder<T> withHeaders(List<SipHeader> headers)
```
  - withPushHeader
```
SipMessage.Builder<T> withPushHeader(SipHeader header)
```
    Push the header to be the first on the list of existing headers already added to this builder. TODO: naming
    
    Returns:
  - onFromHeader
```
SipMessage.Builder<T> onFromHeader(java.util.function.Consumer<AddressParametersHeader.Builder<FromHeader>> f)
```
  - withFromHeader
```
SipMessage.Builder<T> withFromHeader(FromHeader from)
```
    Set the FromHeader to be used by the new SipMessage. If there already is a FromHeader present, either through a template or because this method has been called previously, that value will be overwritten.
    
    Parameters:
    
    from -
    
    Returns:
  - withFromHeader
```
SipMessage.Builder<T> withFromHeader(String from)
```
  - onToHeader
```
SipMessage.Builder<T> onToHeader(java.util.function.Consumer<AddressParametersHeader.Builder<ToHeader>> f)
```
  - withToHeader
```
SipMessage.Builder<T> withToHeader(ToHeader to)
```
  - withToHeader
```
SipMessage.Builder<T> withToHeader(String to)
```
  - onContactHeader
```
SipMessage.Builder<T> onContactHeader(java.util.function.Consumer<AddressParametersHeader.Builder<ContactHeader>> f)
```
  - withContactHeader
```
SipMessage.Builder<T> withContactHeader(ContactHeader contact)
```
  - onCSeqHeader
```
SipMessage.Builder<T> onCSeqHeader(java.util.function.Consumer<CSeqHeader.Builder> f)
```
  - withCSeqHeader
```
SipMessage.Builder<T> withCSeqHeader(CSeqHeader cseq)
```
  - onMaxForwardsHeader
```
SipMessage.Builder<T> onMaxForwardsHeader(java.util.function.Consumer<MaxForwardsHeader.Builder> f)
```
  - withMaxForwardsHeader
```
SipMessage.Builder<T> withMaxForwardsHeader(MaxForwardsHeader maxForwards)
```
  - withCallIdHeader
```
SipMessage.Builder<T> withCallIdHeader(CallIdHeader callID)
```
  - onTopMostRouteHeader
```
SipMessage.Builder<T> onTopMostRouteHeader(java.util.function.Consumer<AddressParametersHeader.Builder<RouteHeader>> f)
```
    Called when the top-most Route header is processed. If there are more than one Route header present, the other ones will be processed via the onRouteHeader(Consumer)
    
    Parameters:
    
    f -
    
    Returns:
  - onRouteHeader
```
SipMessage.Builder<T> onRouteHeader(java.util.function.Consumer<AddressParametersHeader.Builder<RouteHeader>> f)
```
    Called when a Route header is processed (except for the top-most one, then onTopMostRouteHeader(Consumer) is called instead)
    
    Parameters:
    
    f -
    
    Returns:
  - withRouteHeader
```
SipMessage.Builder<T> withRouteHeader(RouteHeader route)
```
    Set a Router header to be used on the message that is being built. This will replace any previously set Route headers. If you wish to add a number of Route headers, use withRouteHeaders(RouteHeader...). If you want to push a Route header to a potentially already existing list of Record Route headers, then use withTopMostRouteHeader(RouteHeader)
    
    Parameters:
    
    route -
    
    Returns:
  - withRouteHeaders
```
SipMessage.Builder<T> withRouteHeaders(RouteHeader... routes)
```
    Set a list of Route headers. Any previously Route headers will be replaced by this list.
    
    Parameters:
    
    route -
    
    Returns:
  - withRouteHeaders
```
SipMessage.Builder<T> withRouteHeaders(List<RouteHeader> routes)
```
  - withTopMostRouteHeader
```
SipMessage.Builder<T> withTopMostRouteHeader(RouteHeader route)
```
    Push the given Route header to the top of the potential list of existing Route headers.
    
    Parameters:
    
    recordRoute -
    
    Returns:
  - withPoppedRoute
```
SipMessage.Builder<T> withPoppedRoute()
```
    Pop the top-most route. Note, if you e.g. add a RouteHeader via the method withTopMostRouteHeader(RouteHeader) followed by this method, then the route you just added will be removed again. Order is important! Note: if you actually wanted to know the value of that RouteHeader then you should really have checked it on the SipMessage you received and not on the builder object.
    
    Returns:
  - withNoRoutes
```
SipMessage.Builder<T> withNoRoutes()
```
    Sometimes you may want to just wipe out all the potential RouteHeaders that e.g. were automatically copied from another SipRequest that was used as a template. A common scenario is that you are building a B2BUA acting as the border police to your network and you simply cannot trust incoming requests and as such, you should not honor externally pushed routes, since if you did, an attacker could by-pass your next hop by forcing the request to go to somewhere else.
    
    Returns:
  - onTopMostRecordRouteHeader
```
SipMessage.Builder<T> onTopMostRecordRouteHeader(java.util.function.Consumer<AddressParametersHeader.Builder<RecordRouteHeader>> f)
```
    Called when the top-most Record Route header is processed. If there are more than one Record Route header present, the other ones will be processed via the onRecordRouteHeader(Consumer)
    
    Parameters:
    
    f -
    
    Returns:
  - onRecordRouteHeader
```
SipMessage.Builder<T> onRecordRouteHeader(java.util.function.Consumer<AddressParametersHeader.Builder<RecordRouteHeader>> f)
```
    Called when a Record-Route header is processed (except for the top-most one, then onTopMostRecordRouteHeader(Consumer) is called instead)
    
    Parameters:
    
    f -
    
    Returns:
  - withRecordRouteHeader
```
SipMessage.Builder<T> withRecordRouteHeader(RecordRouteHeader recordRoute)
```
    Set a Record Router header to be used on the message that is being built. This will replace any previously set Record Route headers. If you wish to add a number of Record Route headers, use withRecordRouteHeaders(RecordRouteHeader...). If you want to push a Record Route header to a potentially already existing list of Record Route headers, then use
    
    Parameters:
    
    recordRoute -
    
    Returns:
  - withRecordRouteHeaders
```
SipMessage.Builder<T> withRecordRouteHeaders(RecordRouteHeader... recordRoute)
```
    Set a list of Record Route headers. Any previously Record Route headers will be replaced by this list.
    
    Parameters:
    
    recordRoute -
    
    Returns:
  - withRecordRouteHeaders
```
SipMessage.Builder<T> withRecordRouteHeaders(List<RecordRouteHeader> recordRoute)
```
  - withTopMostRecordRouteHeader
```
SipMessage.Builder<T> withTopMostRecordRouteHeader(RecordRouteHeader recordRoute)
```
    Push the given Record Route header to the top of the potential list of existing Record Route headers.
    
    Parameters:
    
    recordRoute -
    
    Returns:
  - onRequestURI
```
SipMessage.Builder<T> onRequestURI(java.util.function.Function<SipURI,SipURI> f)
```
    Parameters:
    
    f -
    
    Returns:
  - onTopMostViaHeader
```
SipMessage.Builder<T> onTopMostViaHeader(java.util.function.Consumer<ViaHeader.Builder> f)
```
    Called when the top-most Via header is processed. If there are more than one Via header present, the other ones will be processed via the io.pkts.packet.sip.SipMessage.Builder#onViaHeader(Consumer) consumer
    
    Parameters:
    
    f -
    
    Returns:
  - onViaHeader
```
SipMessage.Builder<T> onViaHeader(java.util.function.BiConsumer<Integer,ViaHeader.Builder> f)
```
    Called when a Via header is processed and the first argument is the index of the Via being processed. The top-most Via header will NEVER be passed to this registered function but rather to the one explicitly meant for processing the top-most via (see onTopMostViaHeader(Consumer). I.e., Let's say you have the following message (request or response, same same): ... Via: SIP/2.0/TCP 12.13.14.15;branch=z9hG4bK-asdf Via: SIP/2.0/UDP 60.61.62.63;branch=z9hG4bK-1234 Via: SIP/2.0/UDP 96.97.98.99;branch=z9hG4bK-wxyz ...
    - When the top-most via header (12.13.14.15) is processed, the function registered with onTopMostViaHeader(Consumer) will be called.
    - When the second via is processed (60.61.62.63), the function registered with onViaHeader(BiConsumer) will be called where the index will be '1' since this is the second via on the list and we of course start counting at zero.
    - When the third via is processed (96.97.98.99), the function registered with onViaHeader(BiConsumer) will be called where the index will be '2' since this is the third via on the list and so on...
    Parameters:
    
    f -
    
    Returns:
  - withViaHeader
```
SipMessage.Builder<T> withViaHeader(ViaHeader via)
```
    Add a Via header to be used on the message that is being built. This will replace any previously set Via headers. If you wish to add a number of Via headers, use withViaHeaders(ViaHeader...). If you want to push a Via header to a potentially already existing list of Via headers, then use withTopMostViaHeader(ViaHeader).
    
    Parameters:
    
    recordRoute -
    
    Returns:
  - withViaHeaders
```
SipMessage.Builder<T> withViaHeaders(ViaHeader... vias)
```
    Set a list of Via headers. Any previously Via headers will be replaced by this list.
    
    Parameters:
    
    recordRoute -
    
    Returns:
  - withViaHeaders
```
SipMessage.Builder<T> withViaHeaders(List<ViaHeader> vias)
```
    Set a list of Via headers. Any previously Via headers will be replaced by this list.
    
    Parameters:
    
    recordRoute -
    
    Returns:
  - withTopMostViaHeader
```
SipMessage.Builder<T> withTopMostViaHeader(ViaHeader via)
```
    Push the given Via header to the top of the potential list of existing Via headers.
    
    Parameters:
    
    recordRoute -
    
    Returns:
  - withTopMostViaHeader
```
SipMessage.Builder<T> withTopMostViaHeader()
```
    Typically the ViaHeader will have to be filled out by the stack at some later point, which is when the message is about to be sent, so when you create the message you don't have all the details just yet. However, just to create a new Via with bogus information only to be re-written later by registering a function with onTopMostViaHeader(Consumer) is rather silly so therefore you can just indicate that you want a new top-most via header but you will fill out all details later. NOTE: if you do NOT register a function to handle this "empty" Via-header through the method onTopMostViaHeader(Consumer) things will blow up later with you try to build this message.
    
    Returns:
  - withPoppedVia
```
SipMessage.Builder<T> withPoppedVia()
```
    Pop the top-most via. Note, if you e.g. add a ViaHeader through the method withTopMostViaHeader(ViaHeader) followed by this method, then the Via you just added will be removed again. Order is important! Note: if you actually wanted to know the value of that ViaHeader then you should really have checked it on the SipMessage you received and not on the builder object.
    
    Returns:
  - withBody
```
SipMessage.Builder<T> withBody(Buffer body)
```
  - build
```
T build()
```
  - onCommit
```
SipMessage.Builder<T> onCommit(java.util.function.Consumer<SipMessage> f)
```
    After the SipMessage has been fully built and created the "end result" will be conveyed to the registered function. It is utterly important that the function returns as quickly as possible since the build method will not be able to return until the call to this function has been completed.
    
    Parameters:
    
    f -

Interface SipMessage.Builder<T extends SipMessage>

Method Summary

Method Detail

isSipRequestBuilder

isSipResponseBuilder

toSipRequestBuilder

toSipResponseBuilder

withNoDefaults

onHeader

withHeader

withHeaders

withPushHeader

onFromHeader

withFromHeader

withFromHeader

onToHeader

withToHeader

withToHeader

onContactHeader

withContactHeader

onCSeqHeader

withCSeqHeader

onMaxForwardsHeader

withMaxForwardsHeader

withCallIdHeader

onTopMostRouteHeader

onRouteHeader

withRouteHeader

withRouteHeaders

withRouteHeaders

withTopMostRouteHeader

withPoppedRoute

withNoRoutes

onTopMostRecordRouteHeader

onRecordRouteHeader

withRecordRouteHeader

withRecordRouteHeaders

withRecordRouteHeaders

withTopMostRecordRouteHeader

onRequestURI

onTopMostViaHeader

onViaHeader

withViaHeader

withViaHeaders

withViaHeaders

withTopMostViaHeader

withTopMostViaHeader

withPoppedVia

withBody

build

onCommit