Subject: [SIP] JAIN SIP discussions @ SIP Bakeoff

From: Chris Harris <[email-masked]>
Date: Mon, 11 Dec 2000 16:04:50 +0000

Folks,

There were some in-depth discussions about the JAIN SIP API at the SIP
Bakeoff last week, and some interesting suggestions arose:

If you are getting an optional parameter/header/body - you should not
throw a
ParameterNotSetException/HeaderNotSetException/BodyNotSetException since
these are not exceptional cases - returning null is preferable, as seen
in other APIs.

The use of arrays for getting and setting multiple values is not nice at
all - why not return an Enumeration/Iterator? (Although according to the
Collections framework documentation it is preferable to pass a generic
Collection and return the most specific subinterface of Collection we
can - possibly SortedList?)

Currently the JainSipProvider always passes a clone of a received
Message to an application. It was suggested that this is too
inefficient, and that it would be preferable to pass a reference to the
Message, and warn in the documentation that the API user must clone the
Message or part of it if they want to do anything other than get its
values. (Personally I find this approach unacceptable - I think it gives
the API user too much scope to mess with the internals of an API
implementation)

Currently get methods in Header interfaces throw a JainSipParseException
if the header value could not be parsed (i.e. an implementation is
allowed to delay parsing until the user asks for a particular part of a
header). It was suggested that it would be better to throw the
JainSipParseException on the getHeader and getXXXHeader methods i.e.
force parsing of the header value when the user asks for the Header
object. It was suggested that the getHeaders and getXXXHeaders methods
(which return multiple headers) shouldn't throw a JainSipParseException,
but that the methods for getting an individual header in the
Enumeration/Iterator/Collection should throw the exception.

[Note that a JainSipParseException contains a String field called
unparsable - but do we need a JainSipParseException that includes a
reference to a Header object - since this will not be returned if the
exception is thrown? This would be particularly useful for the method
getHeaders() which returns all headers in a message - if the exception
is thrown with just the unparsable header value, then the application
has no way to determine the header name. So I suggest that there should
be a JainSipParseException subclass for this case of header value
lazy-parsing e.g. JainSipHeaderValueParseException (extends
JainSipParseException?) which has a getHeader() method - then the
application can call getName() and getValue() on this header object]

Do not need UndefinedHeader or UndefinedRequestMessage - does not add
any functionality to Header or RequestMessage.

Do not need InviteMessage, AckMessage, ByeMessage, CancelMessage,
OptionsMessage or RegisterMessage - they add no extra functionality and
only differ by their method - RequestMessage is sufficient.

Do not need header types - do not provide anything meaningful - header
types alone do not give enough information to do anything useful with an
unrecognised header - the default protocol behaviour is sufficient.

Do not need setName() method in Header - it should be read-only.

I would be grateful if you could send any comments on these suggestions
immediately, so we can get the first public release out asap.

Regards,
Chris Harris

_______________________________________________
SIP mailing list
[email-masked]
http://lists.bell-labs.com/mailman/listinfo/sip

---

From: Gethin Liddell <[email-masked]>
Date: Mon, 11 Dec 2000 17:17:46 +0000

hay chris, 

any points i have not commented on, i agree with (as per our meeting
last week)

> the API user too much scope to mess with the internals of an API

OK, but keep in mind that JAIN SIP will be limited in what it can
achieve effectively if this is done. i.e. it would be no good trying
to create a real proxy with JAIN SIP because it would be very slow.

as i said at our meeting, we need to do what we can to help the
performance of JAIN SIP.

> application can call getName() and getValue() on this header object]

this seems reasonable now. trying to set an incorrect value would throw
a JainSipParseException and trying to parse a header would throw a
JainSipHeaderValueParseException (why not just
JainSipHeaderParseException though? shorter by a whole 5 letters :) )

Although (as a reminder) what about the discussion we had on the minimal
parsing required. i.e. Jain Sip is transaction aware.  therefore each
implmentation needs to at least parse the transaction identifiers, To,
From, Call-ID and CSeq. so for the message to reach the app, then these
heades must be valid and there is no need to throw exceptions on them.
no?

> only differ by their method - RequestMessage is sufficient.

minimal is best

-- 
Gethin Liddell
Ubiquity Software Corporation

http://www.ubiquity.net
mailto:[email-masked]

---

From: Chris Harris <[email-masked]>
Date: Mon, 11 Dec 2000 17:05:12 +0000

Hi Gethin,

Thanks for the quick response. Some notes below...

Chris

> as i said at our meeting, we need to do what we can to help the

I hear what you're saying - but also let's not forget that the implementor has
total control over the cloning of messages - so for high performance JAIN SIP
applications you should use an implementation that doesn't create messages
from scratch each time it clones one - A good implementation will pool JAIN
SIP objects and give the clone operation access to these pools. I would see
this as another way for implementations to distinguish themselves from their
competition. [Although I have a feeling you will come back with saying this
will be even faster if we give the application the decision of whether to
clone or not :) ]

Like I said before: "Safety versus Speed". I would prefer to see safety built
in the API and speed determined by the implementation, rather than speed built
into the API and safety determined by the application.

> JainSipHeaderParseException though? shorter by a whole 5 letters :) )

Sure - although I am starting to think that it might be better to add a header
name field to the JainSipHeaderParseException rather than a header object
field.

> heades must be valid and there is no need to throw exceptions on them.

This is true, and I totally forgot about it - must be the jet lag :)

---

From: Bryan Thale <[email-masked]>
Date: Mon, 11 Dec 2000 12:54:25 -0600

Chris,

Comments and musings below.

Bryan.

> into the API and safety determined by the application.

In that case, shouldn't the API define public message and header
interfaces that contain only get and test accessor methods and no set
methods?  Set methods could be added by private-to-the-stack extensions
to those interfaces.  That would prevent an application from messing
with anything internal and not rely on the good behavior of the
application, nor would it dictate cloning policy.

All the same, though, why is it necessary for the message and header
objects to be owned by and internal to the stack anyway?  They are
merely encapsulations of data that should be able to be freely exchanged
between the application and the stack across the API boundary  just like
a String object can be.  What is dangerous about letting the application
set a value in a header or message object?  Isn't that what an
application is _supposed_ to do?

> > > can - possibly SortedList?)

If the API specified a Collection, couldn't the choice of concrete
representation be left up to the implementation?  That is, the API
wouldn't need to specify that the Collection must be backed up by a
SortedList but could be any Collection-derivative appropriate to the
implementation.

> > > Enumeration/Iterator/Collection should throw the exception.

I think this sounds like a vast ease-of-use improvement for applications
trying to use the API.  It seems rather onerous to force an application
to catch, and theoretically deal intelligently with, a
JainSipParseException whenever it calls something as innocent as
hasQValue().

> name field to the JainSipHeaderParseException rather than a header object

I think the header name is preferable since you might not be able to
construct a meaningful header object in the presence of a parsing error.

> > > these are not exceptional cases - returning null is preferable, as seen

Yes, there is nothing exceptional about the absence of an optional
element.

Speaking of exceptions, it seems like IllegalArgumentException is used
to signal a null parameter being passed in to most methods.  Why not
throw the more precise NullPointerException instead?

--
Bryan Thale
Motorola Labs, Networking and Infrastructure Research
mailto:[email-masked]

---

From: Chris Harris <[email-masked]>
Date: Mon, 11 Dec 2000 20:10:13 +0000

Bryan,

We need to make sure that an implementation does not let an application alter the
original received message (which will may be stored in some transaction object). We
can do this several ways:

   * Simply don't allow an implementation to give a message object to an application
     that it does not wish to be altered externally
   * Allow an implementation to give a message object to an application that it does
     not wish to be altered externally, but warn that an application must not alter
     this message (even though the set methods are available)
   * Allow an implementation to give a message object to an application that it does
     not wish to be altered externally, but only expoose it through a read-only
     interface without set/remove methods

I think the first option is the simplest, the second is a no go, and the third is a
possibility - but it means having 2/3 interfaces for each message and header - one
read-only and another read-write (and maybe one writable). We also need to allow the
application to create a read-write clone of these read-only objects - a regular
clone and downcast to the read-write interface would suffice, but it would be a lot
nicer to define a method that both clones and downcasts. (Of course there would be
nothing stopping an application downcasting the originally received message/header
to alter it - but at least it would be a lot more obvious to the developer that you
shouldn't).

Regards,
Chris

---

From: "M. Ranganathan" <[email-masked]>
Date: Mon, 11 Dec 2000 15:17:51 -0500

¡®+…©ä±ú+¦‹-Šx-†+ŠØZ–Wnyªh–ˆ"zËh¶ŠYlnêòv‹ …º2#¬ž‹ZnW¡«mzwhèZ²Ú!j÷¬¢g†)à¶†Ú‘ê~)è×«¶†µéÝi¶¤z‡ßŒ½êè¦)â¢vyÖ¬!©ˆ²¥•¨«¢˜§Š‰ìjË¬¹©p†'!j·©¢Ë^u·¥£^ªÝ±§ ¡®+jºâ³
èµáh–K…êÞÁêÞ²‰žŠw^¦Ø]ŠÇ.²È¨žÆ›¢ëm…â@ Ôˆ<ÈjÛay"©¡÷åjËpyéÛ(™è§µêÞ²Ø§‚Ë ë-Š‰ìjº,x‡ò¢æ«z¶)àjz)¶*'jZZ©žµêÿ…æz¿Û¡Ü²¢ë!¢é]ž‹m†º0hö«jgz³hµ'¦Ø¨ŸñÞi×«6‹RzÑ1qêmŠ‰ÿ‡r6‹RzÑ1qêmŠ‰ìŠw¶¬yªÞž‹^ÅÇ©¶*'jW±ë+zÛ«ž)àžéeŠÊky÷«i¹^jËzx§¢Ø^¬È°† çˆ0sºYb±«Þ¯*ÞjÊ'i¹^Á¬¨~)Ý‰Æ­Šx-…«Z¥ªÚ™ë^®¬ž‹[yéìzÖ§v+ajÆ¦¦W©çuéÜz)ìz÷«jZeiÇ¬Š{az6¯iªbrœ’‹¶¬kZ®Ç«~ŠÞÅ©©•äá®Œ"ž±qêmŠ‰ì~ŠÜ¢wb¶*'²ØZµªÞž‹^ÅÇ©¶*'r‰ÝŠØ¨žÉš‘ë-…æ©¦XœjØ¨û¥–‡çzË^uì\z›b¢{0†'!ŠÊ®Š×œ¢wî²)à¶‡^j\"¶ázë¡ö«¬¬~ŠàzÛbž§vÇ­¶)àšémŠ™^½©nzÈ¬ž‹g‰Çšµ©eÂ§¢ÚÞ¶êçjq'ºg«jØ¨Ÿò-z¶¢°%¶.‚œrŠÝŠx-¢Ø^
‰eyËb¢{©žÂŠäv‡.™éíjØ¨ž+b²šÞ}êÚnW¢–¬±¨êâp*%•ç-Š‰ÚÚÞ¶êç¶¦¢Ël¥ç"~',¹¸§µêßiÇ¨|*%•ç-Š‰ðyÆ§¦‹,‰¹rJŠíyÒâ²Õ'²êé®+"ž	r!¨+yæ j)È¶§’ØZ´*%•ç-Š‰â²kœ†šÞ}êÚnW¡ªëk&Þq«¬z+\jvÞ{^×jwZuØ­Š‰Ú•û§rØ¨©b·&Þ¦º/‰×jÉÞy×ºÚÉÆ§ž‹[yìmzw^t+«éí—+ax–¢(©>º/‰×«j\ÊÊZ²Ç¬iÉhêj·œz+ÞtÇ¬±¨¶†§jše‰Æ­Š‰È·¬²è zË^vØZ¶Øb²+-¢ˆ§y÷âr'§µ©Ý¶ŠÜ(ºW[zšÞ}êÚnW¢–¬±ªÞ}êÞÇ­¢Ø^1ë,jšÜ®x§¶¡Ë¦z{Z¶*'¶¶€<‹¬z¹®²×%¢w…ã²Æ zŠéj»h~+b~Ø^Ë§¶Ú¡©ò¶§‚‹az»ajx¶+l½©nzÃÞ®Ê'jYr!ø§vØb±ªi®†œ†éÚqÇ©µ¦åx‹aŠy"¶¯zËaxÈºÇ«¶Š&¹ÈlrŠ^¶‰ž²Ì"¶az)íz¹Ú–Êjp")©•éžžÖ­Š‰È0s†+"²z-jšènW¦>ël¶çßŠv¬z–«j×©iÉæ§vf¤yëÞ¯'âzWi®‹^r×Â+aëZÛ¶g†‡ljÌ¨º¯yÚ'xö²)àj·Ÿz·§qè¬8¦§vf¤zÉb}êî«Zuö¬µêÂººÞžÙrëfzØhvÈ§æz¸§µêßiÇ¬¶èÁ¢ZŠt¢¤ö«±á1qêmŠ‰â~Ø^…æz»Ú–çœ¢é]ž‹[z–«±çby©âš™^™éíjØ¨ž+–Z0yÛhuéZÊ–«²)àº{b–Ø^ºÇ«jÉ,~ŠÚ¥ªí‰Ë¥jºZ®ÚjšuêÈ·¬²è zË^vØZ¶+p¢é]mæÞ¶×«¶‹a®Œ-…âZŠt¢¤ö«±á1qêmŠ‰èžØ^ëGy§^©ÝëW]qÞi×«™ëa¡Û"yú+qêZ®È§‚‡í…è^i×«½©n{^žØ^ºÇ«jÉ,~Ší…áÞi×«¡¸ÞrÒ-Á«,º²×¶¶ zÑÞi×«±©ÝëW]qÞi×«²g†‡lÂœ†·º¹æº[b¦W¡y§^®Ë!¢é]žÛa®Œ%¨§J*Oj»¦Ø¨»¶¶¦zØhvÇè®¶)àjx§v+âvæ¥…æz¸§¶„žéž­«b¢ÈµêÚ¶Šÿ
‰eyËb¢{!¢é]¶èÂØ^{¦Ø¨œ‹aŠy-†+&jG¬±éìy×¥k+a®Œ"žayì\z›b¢v¬šç!jÊh²È›•â¶¬ŠÊÞ¶êçyÖ¬iÊ%•ç-Š‰ò¢ì(ºWaj÷¢Øk£aŠÇ±qêmŠ‰ß¢»azw±¶g†‡M¡+œ„I^™éí¦Ø¨œÚ-zØZµ¢ZŠt¢¤ö«±á1qêmŠ‰Ü¢{ZŠ{JÚâžâzW\jY^vééj»nW›º×hÁéÞyÖ‰j)ÒŠ“Ú®Ç„ÅÇ©¶*'¶Šw%¹×¬j·Ÿz·§qëhhwšuêèn7œ¶È§qëaŠÌ"–Yèµ·«zÛ«çb~Ø^{¦Ø¨ž+-†º08b³
.•ÖÞ¥ªí‰Ë¥j¹rºÇŸºWè®Ø^™ëa¡Ø´wšuêìÂœ†·º¹ìjYay§^®È§jg¬±¨‰ûayì\z›b¢x¬¶èÂ|"¶î²Ûazééj»nW¡y§^®ö¥¹ëaz{ayªi–'¶*'…«'£²¶‡^µêæŠw…è^i×«©žNžÅÇ©¶*'ç¢yrr‰íj)í…è^i×«µìmž‰ÞyÛhŠw%¹×­…è^i×«©žNžÅÇ©¶*'…©Ý•êÜjyh¢F¶ŸŠ»-¶‰žÚz×«š)Þ¶¡y§^®v¦x‹lž‹m¢è!¶‡hJ‚,º²ÛajÛaz·¬†‹¥u·š%¨§J*Oj»¦Ø¨žË›rV¬±ú+¶¬q«¡ø^i×«½©nzV³Ê–«²)àzZŠt¢¤wšuêÕj[ž=ªìxL\z›b¢w±µéÝ°–¢(©=ªìxL\z›b¢|!‰ÈajÆ zÑÞi×«™ëa¡Ûaz{ayªi–'¶*'q©ÜjY`zÓZ™æ§vU©nz‰í†+!y§^®†ãyËS¢‡âè+j)ÞvW¬±Ê&¦W±ŠÜ¢±·µêÀ²)à•êZ®ÇžÅÇ©¶*'Âœ†)Ü–ç^²Ø^z{bè^i×«µìmŠÆ¥–ØZ·§yçC¢z-çRw^~)ÞtwšuêèIÝyø§yÔ^ªç¬´Ç¬±¨v‡¬ž‹ZuÖ§Éû§rØ¨©b·+hæzº+Eê®zËLzËàèž‹gyçHžøxÇ¬±¨ÉzËàrxÇ¬±¨	©ÜzS²Æ xêmŠ‰ì1ë,j¨ ŠË^¬Ç¬±¨¶²i×g¡ìm§îËb¢v¥ŠÜšÚ'—'b}÷«o+az*æzØhuª¹ë-1ë,j¢²ËŸ~'"z{@‚·ž«"q©eÉ©eÊ‹§yçb±"1ë,j°†'!ŠË.mÉZ²Ço$^ªç¬´Ç¬±¨jwQz™r1ë,jƒ¢z-ç…æz»r¥ë¢z-¦º/‰×šŸ+aŠx&y©âžî–šuêíÊ—¬jZ'yÚ'¢Ø"½ç§¢è!Šwè®fŠ‰í¡ÚŸ+aŠx.±çî—…©îž·œ¢	â±çay§^®Ø^uçÚº[i®‹hr‰[z¯Š‹«ŠË.}øœ‰éí!¨+yì"¶aŠÆ¥²†(¹Æ§v‡¯z¼†)àÂ+aŠ{k¢Ê^rØ¨žšè¾'bž^i×«·*^²++yÛ§u©í‰è¶wžvÇ­5©ž™ëa¡Ø§æz¸².•ÖÞ­æ¢yrÌ¨ºf²{^rÒ0¢é]‚Š'zË^¥û«¶«b‹¢{gyçlzÕ×\‡ò¢ìžÛhr‰ì¶»œ¶šuêìŽë-¦º/‰×š…æz·è®fµêâž×«}§jÂ(ºÙbçbž‹«¦·¯Š‹¬v+ºË"¢|…§hžØb²Ë›ç-b‹¢{gyçm¢–«±ëaz)éºÛÚ–ç¬jÖ¥•·œjë¶¨¶«zwpŠYm†º0{¦Ø¨©òÁ¬…ç§vÚÖ«‚éžžÜ(ºWfjG¬z{…êÞ=êáj›2¢éšÊÆ²ŠØ¬ž‹N9Ç§¶¸œjwfk&Þ¶«z+¦ˆ§¶Ø^æî¶+b±ö¬µêÚÛ"š™^®ØZž¯zØ^jše‰Æ¢¶‰õv†¬zÚy§!~'¥u©Ýmêkz–«yÛhq«\…ì\z›b¢v§whZ½ëaz6¢žÈ©Šjezg§µ«b¢{Ú–'Zµè§¦ëoj[ž²øš¶©j»©ÝÞ¯zØ^ç"¦'§¶·¯jXj×­…æ«‚éžžÖ§Ë²#
.•ÖÞ‚¶yû¥‰ü¨¹Ê.•ÛÖ§ÉÊ&™éí²‰í…ë²è zËb¢{"šg‰«^—+(Áçž¶ŸŠ»-¦æå‰ÊÞ•æ¬z‹jÆ©#
.•Ü•Ê&y©òš‹Þ¶ŠÞvç¶¬‹7š×(š™^Æ+r¡ûaxÈEèÛ†¸¬ªëŠÄˆ>f¢–)à–+-HƒåŠËlmée•¦ìr‰¡¶ÚþX¬¶ÆÞ–YZnÇ(›ùšŠYšŸùb²Ø§~ìŠ“jx«ajsHI0½©ÜyÓ^·
+’)àMç!ž‰h‚'¬º.§]4êÞjàëŠ÷’¶Š|÷mj+az»º¸m<÷ÔÞ—}5÷¾wë®kô×ŸtÓÝö