3.1 The JAIN SIP Object Model
A JAIN SIP object, or, rather, the class from which it is instantiated,
can be expressed as either a traditional Java program or as a JavaBean
[3], where a JavaBean [3] is a reusable software component/object. An application
(e.g., a Media Gateway Controller) that needs to make use of the services
of a SIP stack that is encapsulated as a JAIN SIP object can also be expressed
in either of these ways, as well.
JAIN is built upon standardized Java APIs and Object technology.
In Object Technology, data and programming logic are treated as objects.
Unlike traditional computer programs, objects can be readily integrated
into a running environment, accessed and managed remotely, and debugged
and maintained in live systems by standardized interfaces, etc.
While JAIN does not mandate that all applications must be built
as JavaBeans [3], the design of the API specification will not preclude
any application from executing as a JavaBean [3]. The unifying features
of a JavaBean [3] are explained with examples at http://java.sun.com/beans/docs/index.html.
The main points are:
-
Introspection: Can be used by an application builder tool to discover
the properties, methods and events of a JAIN SIP object.
-
Customization: Allows an operator to dynamically change the properties
of a JAIN SIP object at run time using an application builder tool.
-
Events: Can be used as the vehicle for bi-directional communication
between an application and a JAIN SIP object, so that the invocation of
a SIP method can be accomplished by the passing of an event object between
the application and the JAIN SIP object that will perform the method.
-
Persistence: Allows the state of a JAIN SIP object to be stored
for retrieval at a later time.
The three most important features of a JavaBeans [3] are:
-
Property Management: Properties are named attributes associated
with a bean that can be read or written by calling appropriate methods
on the bean.
-
Method Management: A JavaBean [3] exports both standard and extended
Java methods, which can be called from other objects or from a scripting
environment, such as HTML invoking an applet. By default, all of the bean's
public methods will be exported.
-
State Management: Events provide a way for one object to notify
other objects that a change in state has occurred. Under the Java event
model, an event listener object can be registered with an event source.
When the event source detects a state change, it will call the appropriate
method on the event listener object.
REQ-OM-01-01: The API specification shall adhere to the JavaBeans Model.
If the JAIN SIP API specification is implemented using JavaBeans [3], it
offers the advantage of using reusable objects in a plug and play fashion.
REQ-OM-02-01: The API specification shall not restrict an implementation
of the API to JavaBeans.
This permits the JAIN SIP API specification to be implemented in standard
Java code.
3.2 JAIN SIP Naming Convention
JAIN SIP objects must conform to a specific naming convention in order
to support JavaBean [3] implementation. For a JavaBean [3] to expose a
property, i.e. within a visual tool, it must supply an access method "get"
to read the property value and/or a "set" method to write the property
value. These "get" and "set" methods have the following signatures:public
<PropertyType>
get<PropertyName>();public void set<PropertyName>(<PropertyType>
a);
If we discover a matching pair of get<PropertyName> and set<PropertyName>
methods that take and return the same type, then we regard these methods
as defining a read-write property whose name will be <PropertyName>.
For a Boolean property the access method "get" signature changes
to:
public boolean is<PropertyName>();
REQ-NC-01-01: The API specification shall follow the JavaBean naming convention.
REQ-NC-02-01: All access methods shall throw an exception when accessing
a parameter that has not previously been set or is not supported by a specific
implementation.
Adherence to this requirement will provide an efficient technique for determining
whether a parameter has been set or is not supported by an implementation,
and for initiating a corrective action. Adherence is also consistent with
Java language programming style.
3.3 JAIN SIP Architecture
For simplicity, the illustration below, Figure 4: JAIN
SIP Architecture, represents a generic SIP Client and a generic SIP
Server.
Figure 4: JAIN SIP Architecture
The TCK and the RI will test the JAIN SIP API specification, where the
TCK is equivalent to the application/SIP Listener and the RI is equivalent
to the SIP stack/SIP Provider. It is important to note that the RI is not
an emulation of a SIP/IP stack.
-
JAIN SIP Events: Within the API, SIP messages are encapsulated as
JAIN SIP Event Objects that are passed between the JAIN SIP Provider and
the JAIN SIP Listener.
-
JAIN SIP Provider: Within the API, the JAIN SIP Provider is defined
as the entity that provides an application access to the services of the
SIP stack. The JAIN SIP Provider acts as the source of a JAIN SIP Event
Object when it receives a request made by a remote application. The request’s
parameters are encapsulated in an Event Object and passed to the JAIN SIP
Listener. The JAIN SIP Provider acts as a sink for a JAIN SIP Event Object
when the application that the JAIN SIP Provider services needs to send
a SIP request to a remote application.
-
JAIN SIP Listener: Within the API, the JAIN SIP Listener is defined
as the entity that uses the services provided by the JAIN SIP Provider.
Thus, the JAIN SIP API must provide definitions for the Listener
and Provider interfaces, for all the Event Objects that correspond to SIP
primitives, and for the means for Listeners to register with corresponding
Providers in order to send and receive these primitives.
3.3.1 Event Requirements
3.3.1.1 JAIN SIP Event Processing
REQ-ER-01-01: The API specification shall provide the functionality that
will enable SIP messages and their associated parameters to be sent between
the JAIN SIP Provider and the JAIN SIP Listener as Events.
JAIN SIP messages are passed between the protocol stack to the application
as Event Objects. Event handling methods defined in the EventListener interface
conform to a standard naming convention:
void <eventOccurrenceMethodName> (<EventStateObjectType>
event);
where the <EventStateObjectType> is a subclass of java.util.EventObject.
Event Provider classes provide methods for registering and de-registering
event listeners, which allow potential EventListeners to establish an event
flow from that Provider to the Listener. The standard naming convention
for EventListener registration is:
public void add<ListenerType> (<ListenerType> listener) throws
java.util.TooManyListenerException, java.util.ListenerAlreadyRegisteredException
The current architecture of SIP makes it unlikely that more than one
Listener would act on a single SIP Event Object, so in that case the API
implementation should preclude more than one Listener from registering
on a given Provider. (An implementation may permit multiple Listeners for
high availability or load-sharing, but this is not specifically addressed
by the API). Note that no requirement is placed on the Listener to catch
the exception that may be thrown. However the ListenerAlreadyRegisteredException
should always be thrown if the same JAIN SIP Listener, tries to re-register
with the JAIN SIP Provider.
public void remove<ListenerType>(<ListenerType> listener)
throws java.util.ListenerNotRegisteredException;
The ListenerNotRegisteredException should always be thrown if this method
is invoked on a specific JAIN SIP Listener, which is not registered with
that JAIN SIP Provider.
An overview of the JAIN SIP Event Processing model is illustrated in
Figure 5: JavaBean™ Event Model.
Figure 5: JavaBean™ Event Model
Invoking the add<ListenerType> method adds the given listener to
the set of Event Listeners registered for events associated with the <ListenerType>.
Similarly invoking the remove<ListenerType> method removes the given
Listener from the set of Event Listeners registered for Events associated
with the <ListenerType>.
The error handling of the possible exceptions are all specific to the
implementation of the JAIN SIP specification, for example:
-
Adding the same JAIN SIP Listener more than once to the same JAIN SIP Provider.
-
Removing a JAIN SIP Listener more than once from the same JAIN SIP Provider.
-
Removing a JAIN SIP Listener that is not registered with a JAIN SIP Provider.
-
Adding more JAIN SIP Listeners than a JAIN SIP Provider can handle.
3.3.1.2 JAIN SIP Events
JAIN SIP Events, which are encapsulated SIP messages, contain both input
parameters provided to the Listener by the Provider and output parameters
returned by the Listener to the Provider.
REQ-ER-02-01: The API specification shall define a method which accepts
a generic Event Object corresponding to all SIP primitives, from the invoking
entity (the Provider), to the registered Listener method that processes
that primitive.
REQ-ER-03-01: The API implementation shall provide methods defined on each
Event Object for accessing both input and output parameters encapsulated
within the Event Object.
This will provide SIP message passing from object to object, by following
the JavaBeans event model. [3]
3.3.2 JAIN SIP Provider Requirements
The implementation of the JAIN SIP Provider interface provides a vendor-specific
SIP stack with the ability to communicate with a JAIN SIP Listener implemented
in an application (e.g., a User Agent or Proxy Server).
REQ-PR-01-01: At most one JAIN SIP Provider shall be bound to a given SIP
port at any time.
Since permitting more than one JAIN SIP Provider on a given SIP port would
not be useful.
REQ-PR-02-01: The JAIN SIP Provider shall pass an Event to at most one
registered JAIN SIP Listener.
Since at most one Listener shall be registered with a given Provider (usually),
violation of this requirement would signify a serious implementation error.
(As mentioned above, an implementation may permit multiple Listeners for
the purposes of high availability or load-sharing, but a JAIN SIP application
must ensure only one Listener actually handles an event)
3.3.2.1 JAIN Factory Requirements
Within Java, a Factory is a means to access vendor-specific implementations
of a Java Interface or API; therefore, the JAIN IP Factory is a means to
access vendor-specific implementations of the JAIN SIP Stack and Provider
Interface.
REQ-PR-03-01: The API specification shall provide a common interface to
access JAIN SIP Provider peers.
This will ensure that additional JAIN SIP Provider peer functionality is
hidden from the JAIN SIP Listener implementation, as well as providing
a common method of instantiating JAIN SIP Provider objects. A common Object-Oriented
design pattern used to handle this in other API's, e.g., JTAPI, is the
Peer Factory.
3.3.3 JAIN SIP Listener Requirements
REQ-LR-01-01: A JAIN SIP Listener shall be able to register with any JAIN
SIP Provider.
This ensures that all JAIN SIP Listeners are portable over all JAIN SIP
Providers, which is a fundamental requirement of the Java programming language
i.e. “write-once, run-anywhere.”
3.3.3.2 JAIN SIP Listener Registration
REQ-LR-03-01: A JAIN SIP Listener shall register with a JAIN SIP Provider
to receive SIP messages from that Provider by using the addListener method
defined by that Provider.
3.4 Generic Primitives
A generic set of primitives shall be created that abstracts the functionality
of the primitives to support extensions.
REQ-GP-01-01: The API shall incorporate a common set of primitives that
will map to protocol extension information.
This provides a higher level of abstraction within the API.
REQ-GP-02-01: The API shall treat all primitives that are not common to
the base protocol as optional.
