org.cafesip.jiplet
Class Jiplet

java.lang.Object
  org.cafesip.jiplet.Jiplet

Direct Known Subclasses:

ProxyJiplet

public class Jiplet
extends java.lang.Object

The Jiplet class is the base class that all Jiplet classes must extend. Jiplets are SIP server-side components. In concept, tt is similar to a Java servlet. A java servlet is a Java object that runs inside a servlet container and handles HTTP requests. Similarly, a jiplet is a Java object that runs inside a Jiplet Container and handles SIP requests. Application developers can create jiplets classes and add them to the Jiplet Container in a manner similar to how servlets are added into a servlet container. To create a jiplet, a new jiplet class must be created that extends this class. To add the custom business logic, the class must overide one or more of the public methods of the Jiplet class. The processRequest(), processResponse(), processTimeout() and processTimers() are the "low-level" methods that are invoked by the jiplet container when a SIP request, response or timeout is received or when a application timer expires. A jiplet can override these methods to provide custom logic. Alternatively, override one of the do...() methods to provide handling for specific requests. The container calls the init() method when the jiplet is initialized. A jiplet class can override this method to provide custom initialization logic. Similarly, the destory() method can be overidden to provide custom logic when the jiplet is removed from service. To integrate logging with that of the container, the debug(), info(), warn(), error(), and fatal() methods are provided. Jiplets can call these methods to print log messages.

Constructor Summary

Jiplet()

Method Summary

void	cancelResponse(JipletTransaction transaction) This method is used to notify the jiplet container that the response is no longer expected.
void	cancelTimer(TimerEvent timer) This method cancels a timer started by the startTimer() methods.
void	debug(java.lang.String message) This method is used to print a debug message into the jiplet containers logs.
void	destroy() This method is called by the jiplet container when the jiplet is being taken out of service or when the context or the container is being shutdown.
void	doAck(JipletRequest request) This method is invoked by the container when a SIP request message of the type ACK is received.
void	doBye(JipletRequest request) This method is invoked by the container when a SIP request message of the type BYE is received.
void	doCancel(JipletRequest request) This method is invoked by the container when a SIP request message of the type CANCEL is received.
void	doExtension(JipletRequest request) This method is invoked by the container when a SIP request message is received that is neither REGISTER, INVITE, ACK, BYE, CANCEL, INFO, MESSAGE, NOTIFY, OPTIONS, PRACK, REFER, SUBSCRIBE OR UPDATE.
void	doInfo(JipletRequest request) This method is invoked by the container when a SIP request message of the type INFO is received.
void	doInvite(JipletRequest request) This method is invoked by the container when a SIP request message of the type INVITE is received.
void	doMessage(JipletRequest request) This method is invoked by the container when a SIP request message of the type MESSAGE is received.
void	doNotify(JipletRequest request) This method is invoked by the container when a SIP request message of the type NOTIFY is received.
void	doOptions(JipletRequest request) This method is invoked by the container when a SIP request message of the type OPTIONS is received.
void	doPrack(JipletRequest request) This method is invoked by the container when a SIP request message of the type PRACK is received.
void	doRegister(JipletRequest request) This method is invoked by the container when a SIP request message of the type REGISTER is received.
void	doSubscribe(JipletRequest request) This method is invoked by the container when a SIP request message of the type SUBSCRIBE is received.
void	doUpdate(JipletRequest request) This method is invoked by the container when a SIP request message of the type UPDATE is received.
void	error(java.lang.String message) This method is used to print an error message into the jiplet containers logs.
void	fatal(java.lang.String message) This method is used to print a fatal message into the jiplet containers logs.
void	forward(JipletEvent event, java.lang.String jiplet) A jiplet can forward a request, response, timeout or a timer expiry event to another jiplet.
javax.sip.address.AddressFactory	getAddressFactory() This method returns the JAIN-SIP AddressFactory object which can then be user to format SIP messages.
protected java.lang.String	getConnectorName() Gets the connector name associated with this jiplet.
JipConnector	getConnectorProperty() Gets the property of the connector to which this jiplet object is attached to.
java.lang.String	getDescription() This method returns the description of the jiplet.
JipletDialog	getDialog(javax.sip.Dialog dialog, boolean create) This method is used to get a JipletDialog object.
javax.sip.header.HeaderFactory	getHeaderFactory() This method returns the JAIN-SIP HeaderFactory object which can then be user to format SIP messages.
protected java.util.HashMap	getInitParams() Returns the init paramters that has been specified in the jip.xml file.
JipletContext	getJipletContext() This method returns the context.
javax.sip.ListeningPoint	getListeningPointDefault() Returns the JAIN-SIP listening point that has been designated as the default listening point for this jiplet's SIP connector.
java.util.ArrayList	getListeningPoints() Returns all of the JAIN-SIP listening points that have been configured for this jiplet's SIP connector.
javax.sip.message.MessageFactory	getMessageFactory() This method returns the JAIN-SIP MessageFactory object which can then be user to format SIP messages.
java.lang.String	getName() Returns the name of the jiplet.
javax.sip.SipProvider	getSipProvider(javax.sip.ListeningPoint lp) Returns the JAIN-SIP SIP provider corresponding to the given listening point.
javax.sip.SipProvider	getSipProvider(java.lang.String address, int port) Returns the JAIN-SIP SIP provider associated with the given host address and port.
boolean	hasAddress(java.lang.String host, int port) Indicates if this jiplet's SIP connector is handling (owns) the given host/port or not.
void	info(java.lang.String message) This method is used to print an informational message into the jiplet containers logs.
void	init(JipletConfig config) The init() method is called by the jiplet container when the jiplet is being initialized.
boolean	isDebugEnabled() The debug is a flag that indicates whether the container is is "debug" mode.
void	processRequest(JipletRequest request) This method is invoked by the container when a SIP request message is received that matches the selection criteria for the jiplet.
void	processResponse(JipletResponse response) This method is invoked by the container when a SIP response message is received.
void	processSignal(JipletSignal signal) This method is called by the jiplet container to notify the jiplet of an event (signal) from an external entity.
void	processTimeout(JipletTimeout timeout) This method is invoked by the container when a SIP time-out event occurs.
void	processTimer(JipletTimer timer) A jiplet may start timers by calling the method startTimer().
JipletTransaction	registerForResponse(javax.sip.message.Request request) This method is similar to the registerForResponse(Request request, long timeout) except that it does not have a timeout parameter.
JipletTransaction	registerForResponse(javax.sip.message.Request request, long timeout) This method is used by the server to register for a SIP response message.
void	setAddressFactory(javax.sip.address.AddressFactory addressFactory)
protected void	setConnector(SipConnector connector)
void	setDescription(java.lang.String description)
void	setHeaderFactory(javax.sip.header.HeaderFactory headerFactory)
protected void	setInitParams(java.util.HashMap initParams)
void	setJipletContext(JipletContext jipletContext)
void	setMessageFactory(javax.sip.message.MessageFactory messageFactory)
void	setName(java.lang.String name)
TimerEvent	startTimer(java.util.Date time, JipletEvent event, java.lang.Object param) Similar to the startTimer(long delay, boolean repeat, JipletEvent event, Object param) method.
TimerEvent	startTimer(java.util.Date firstTime, long period, JipletEvent event, java.lang.Object param) Similar to the startTimer(Date time, JipletEvent event, Object param) method.
TimerEvent	startTimer(long delay, boolean repeat, JipletEvent event, java.lang.Object param) This method is used to start a timer.
TimerEvent	startTimer(long delay, JipletEvent event, java.lang.Object param) Similar to the startTimer(long delay, boolean repeat, JipletEvent event, Object param) method.
java.lang.String	toString()
void	warn(java.lang.String message) This method is used to print a warning message into the jiplet containers logs.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Jiplet

public Jiplet()

Method Detail

getJipletContext

public JipletContext getJipletContext()

This method returns the context. The jiplet container can host multiple contexts. Each jiplet is a part of a context. This method returns the context of the current jiplet.

Returns:

Returns the jipletContext.

setJipletContext

public void setJipletContext(JipletContext jipletContext)

Parameters:

jipletContext - The jipletContext to set.

init

public void init(JipletConfig config)
          throws JipletException

The init() method is called by the jiplet container when the jiplet is being initialized. Jiplet classes extending this class must override this method in order to provide custom initialization logic.

Parameters:

config - object containing the jiplet configuration. The jiplet configuration is specified in the file context.JIP-INF/jip.xml.

Throws:

JipletException

destroy

public void destroy()

This method is called by the jiplet container when the jiplet is being taken out of service or when the context or the container is being shutdown. Jiplets extending this class may override this method in order to provide custom finalization logic.

getName

public final java.lang.String getName()

Returns the name of the jiplet. The name is specified in the jip.xml configuration file.

Returns:

the name of the jiplet

getDescription

public final java.lang.String getDescription()

This method returns the description of the jiplet. The description is specified in the file jip.xml.

Returns:

the description

processRequest

public void processRequest(JipletRequest request)

This method is invoked by the container when a SIP request message is received that matches the selection criteria for the jiplet. The selection criteria is specified in the descriptor file jip.xml. This method calls one of the do...() methods depending on the type of the request message. A jiplet class extending this class may override this method in order to provide the logic for handling SIP request messages. However, note that it may be more useful to override one or more of the do...() methods instead. If this method is overridden, the do..() methods do not get called.

Parameters:

request - the request object.

doExtension

public void doExtension(JipletRequest request)

This method is invoked by the container when a SIP request message is received that is neither REGISTER, INVITE, ACK, BYE, CANCEL, INFO, MESSAGE, NOTIFY, OPTIONS, PRACK, REFER, SUBSCRIBE OR UPDATE. A jiplet extending this class may override this method in order to provide custom handling logic.

Parameters:

request - request object.

doUpdate

public void doUpdate(JipletRequest request)

This method is invoked by the container when a SIP request message of the type UPDATE is received. A jiplet extending this class may override this method in order to provide custom handling logic.

Parameters:

request - request object.

doSubscribe

public void doSubscribe(JipletRequest request)

This method is invoked by the container when a SIP request message of the type SUBSCRIBE is received. A jiplet extending this class may override this method in order to provide custom handling logic.

Parameters:

request - request object.

doPrack

public void doPrack(JipletRequest request)

This method is invoked by the container when a SIP request message of the type PRACK is received. A jiplet extending this class may override this method in order to provide custom handling logic.

Parameters:

request - request object.

doOptions

public void doOptions(JipletRequest request)

This method is invoked by the container when a SIP request message of the type OPTIONS is received. A jiplet extending this class may override this method in order to provide custom handling logic.

Parameters:

request - request object.

doNotify

public void doNotify(JipletRequest request)

This method is invoked by the container when a SIP request message of the type NOTIFY is received. A jiplet extending this class may override this method in order to provide custom handling logic.

Parameters:

request - request object.

doMessage

public void doMessage(JipletRequest request)

This method is invoked by the container when a SIP request message of the type MESSAGE is received. A jiplet extending this class may override this method in order to provide custom handling logic.

Parameters:

request - request object.

doInfo

public void doInfo(JipletRequest request)

This method is invoked by the container when a SIP request message of the type INFO is received. A jiplet extending this class may override this method in order to provide custom handling logic.

Parameters:

request - request object.

doCancel

public void doCancel(JipletRequest request)

This method is invoked by the container when a SIP request message of the type CANCEL is received. A jiplet extending this class may override this method in order to provide custom handling logic.

Parameters:

request - request object.

doBye

public void doBye(JipletRequest request)

This method is invoked by the container when a SIP request message of the type BYE is received. A jiplet extending this class may override this method in order to provide custom handling logic.

Parameters:

request - request object.

doAck

public void doAck(JipletRequest request)

This method is invoked by the container when a SIP request message of the type ACK is received. A jiplet extending this class may override this method in order to provide custom handling logic.

Parameters:

request - request object.

doInvite

public void doInvite(JipletRequest request)

This method is invoked by the container when a SIP request message of the type INVITE is received. A jiplet extending this class may override this method in order to provide custom handling logic.

Parameters:

request - request object.

doRegister

public void doRegister(JipletRequest request)

This method is invoked by the container when a SIP request message of the type REGISTER is received. A jiplet extending this class may override this method in order to provide custom handling logic.

Parameters:

request - request object.

processResponse

public void processResponse(JipletResponse response)

This method is invoked by the container when a SIP response message is received. The response message is always routed to the same jiplet that sent the request message. A jiplet extending this class may override this method in order to provide custom handling logic.

Parameters:

response - response object.

processTimeout

public void processTimeout(JipletTimeout timeout)

This method is invoked by the container when a SIP time-out event occurs. A timeout event is reported by the SIP protocol stack when it is unable to send a message or when a response message is not received within a specified period of time. For more details, see the SIP specifications as well as the JAIN-SIP specificationa. A jiplet extending this class may override this method in order to provide custom handling logic.

Parameters:

timeout - timeout object.

processTimer

public void processTimer(JipletTimer timer)

A jiplet may start timers by calling the method startTimer(). The container starts a timer of the duration specified by the call. When the timer expires, this method is invoked by the container. A jiplet extending this class must override this method in order to provide custom handling logic.

Parameters:

timer - The timer object.

setDescription

public final void setDescription(java.lang.String description)

Parameters:

description - The description to set.

setName

public final void setName(java.lang.String name)

Parameters:

name - The name to set.

getAddressFactory

public final javax.sip.address.AddressFactory getAddressFactory()

This method returns the JAIN-SIP AddressFactory object which can then be user to format SIP messages. See the JAIN-SIP API documentation for details. This object is set by the container when the jiplet is being initiliazed.

Returns:

Returns the AddressFactory object.

setAddressFactory

public final void setAddressFactory(javax.sip.address.AddressFactory addressFactory)

Parameters:

addressFactory - The addressFactory to set.

getHeaderFactory

public final javax.sip.header.HeaderFactory getHeaderFactory()

This method returns the JAIN-SIP HeaderFactory object which can then be user to format SIP messages. See the JAIN-SIP API documentation for details. This object is set by the container when the jiplet is being initiliazed.

Returns:

Returns the HeaderFactory object.

setHeaderFactory

public final void setHeaderFactory(javax.sip.header.HeaderFactory headerFactory)

Parameters:

headerFactory - The headerFactory to set.

getMessageFactory

public final javax.sip.message.MessageFactory getMessageFactory()

This method returns the JAIN-SIP MessageFactory object which can then be user to format SIP messages. See the JAIN-SIP API documentation for details. This object is set by the container when the jiplet is being initiliazed.

Returns:

Returns the MessageFactory object.

setMessageFactory

public final void setMessageFactory(javax.sip.message.MessageFactory messageFactory)

Parameters:

messageFactory - The messageFactory to set.

info

public final void info(java.lang.String message)

This method is used to print an informational message into the jiplet containers logs. The log messages are handled by the jiplet container using LOG4J. The LOG4J appenders and formatters are defined in the file conf/log4j.xml. This method allows the jiplets to integrate logging with that of the jiplet container.

Parameters:

message - message to print

warn

public final void warn(java.lang.String message)

This method is used to print a warning message into the jiplet containers logs. The log messages are handled by the jiplet container using LOG4J. The LOG4J appenders and formatters are defined in the file conf/log4j.xml. This method allows the jiplets to integrate logging with that of the jiplet container.

Parameters:

message - message to print

error

public final void error(java.lang.String message)

This method is used to print an error message into the jiplet containers logs. The log messages are handled by the jiplet container using LOG4J. The LOG4J appenders and formatters are defined in the file conf/log4j.xml. This method allows the jiplets to integrate logging with that of the jiplet container.

Parameters:

message - message to print

fatal

public final void fatal(java.lang.String message)

This method is used to print a fatal message into the jiplet containers logs. The log messages are handled by the jiplet container using LOG4J. The LOG4J appenders and formatters are defined in the file conf/log4j.xml. This method allows the jiplets to integrate logging with that of the jiplet container.

Parameters:

message - message to print

debug

public final void debug(java.lang.String message)

This method is used to print a debug message into the jiplet containers logs. The log messages are handled by the jiplet container using LOG4J. The LOG4J appenders and formatters are defined in the file conf/log4j.xml. This method allows the jiplets to integrate logging with that of the jiplet container.

Parameters:

message - message to print

isDebugEnabled

public final boolean isDebugEnabled()

The debug is a flag that indicates whether the container is is "debug" mode. In debug mode, the container prints a lot of debug information that can be used to debug problems. The debug messages are printed by the jiplet by calling the debug() method. The debug mode can be enabled or disabled from the log4j.xml file. In production systems, it is not recommended to turn the debug mode on because of the high overhead.

Returns:

returns true if debug is enabled, false otherwise.

forward

public final void forward(JipletEvent event,
                          java.lang.String jiplet)

A jiplet can forward a request, response, timeout or a timer expiry event to another jiplet. As explained in this class document, when a request, response, timeout or a timer expiry event occurs, the jiplet container calls one of the processRequest() (or do..() methods()), processResponse(), processTimeout() or processTimer() methods to notify the jiplet of the request. From these methods, a jiplet may call te forward() method to forward the requets to another jiplet. The jiplet to which the event is forwarded, gets notified when this jiplet returns from the process...() or the do...() method. The event scope variables are retained across a forward similar to web servlets.

Parameters:

event - the event object (passed on as a parameter to the process..() or do...() methods).

jiplet - the jiplet object to forward the event to.

startTimer

public final TimerEvent startTimer(long delay,
                                   boolean repeat,
                                   JipletEvent event,
                                   java.lang.Object param)

This method is used to start a timer. The jiplet container provides a timer service. When a timer is started by calling the startTimer() method, the jiplet container starts a timer thread. When the timer expires, the processTimer() method is called by the container.

Parameters:

delay - the duration of the timer in milliseconds.

repeat - true if the timer is to be repeated.

event - the request/response/timeout/timer object that was received as a parameter for the process...() or do...() methods.

param - An object that the jiplet can specify. This object is returned when the timer expires as a part of the timer object in the processTimer() request.

Returns:

a TimerEvent object if the timer was successfully started, null otherwise.

startTimer

public final TimerEvent startTimer(long delay,
                                   JipletEvent event,
                                   java.lang.Object param)

Similar to the startTimer(long delay, boolean repeat, JipletEvent event, Object param) method. This method is used to start a non-repeatable timer.

Parameters:

delay -

event -

param -

Returns:

An object used for cancelling the timer

startTimer

public final TimerEvent startTimer(java.util.Date time,
                                   JipletEvent event,
                                   java.lang.Object param)

Similar to the startTimer(long delay, boolean repeat, JipletEvent event, Object param) method. This method is used to start a timer that expires at the specified time.

Parameters:

time - the absolute time when the timer expires.

event -

param -

Returns:

An object which can be used to cancel the timer

startTimer

public final TimerEvent startTimer(java.util.Date firstTime,
                                   long period,
                                   JipletEvent event,
                                   java.lang.Object param)

Similar to the startTimer(Date time, JipletEvent event, Object param) method. This method is used to start a timer that expires at the specified time and is repeated every so many milliseconds after that.

Parameters:

firstTime - the absolute time when the timer expires for the first time.

period - of time in milliseconds after which the timer expires periodically.

event -

param -

Returns:

An object that can be used to cancel the timer

cancelTimer

public final void cancelTimer(TimerEvent timer)

This method cancels a timer started by the startTimer() methods.

Parameters:

timer - the object returned by the startTimer() method.

setConnector

protected final void setConnector(SipConnector connector)

Parameters:

connector - The connector to set.

getConnectorName

protected final java.lang.String getConnectorName()

Gets the connector name associated with this jiplet. A connector is a SIP messaging entity that has one or more "ports". A port is an an IP address/port/protocol that the container listens to for messages from UAC. The jiplet container supports multiple connectors and each connector can support multiple IP addresses; a jiplet is associated with one connector. This is configured in the jip.xml descriptor file.

Returns:

the connector name

getListeningPointDefault

public final javax.sip.ListeningPoint getListeningPointDefault()

Returns the JAIN-SIP listening point that has been designated as the default listening point for this jiplet's SIP connector. The designation is done in the server.xml config file. The default listening point information may be needed by a jiplet when composing VIA and other headers like record-route. It is commonly used to get the default SipProvider (by calling Jiplet.getSipProvider()) in order to send an out-of-dialog Request message.

Returns:

The designated default javax.sip.ListeningPoint for this jiplet.

getSipProvider

public final javax.sip.SipProvider getSipProvider(javax.sip.ListeningPoint lp)

Returns the JAIN-SIP SIP provider corresponding to the given listening point.

Parameters:

lp - The javax.sip.ListeningPoint.

Returns:

The javax.sip.SipProvider that is associated with the given listening point.

getSipProvider

public final javax.sip.SipProvider getSipProvider(java.lang.String address,
                                                  int port)

Returns the JAIN-SIP SIP provider associated with the given host address and port. The SIP providers are created based on the jip-ports in the server.xml config file. For each unique address + port combination, a SIP provider is created. Within that, for each transport configured for that address + port combination, a listening point is created and associated with the SIP provider. This method can determine which SipProvider is serving the given address and port.

Parameters:

address - The host address known by the caller.

port - The port known by the caller.

Returns:

The javax.sip.SipProvider that is associated with the given address and port.

getListeningPoints

public final java.util.ArrayList getListeningPoints()

Returns all of the JAIN-SIP listening points that have been configured for this jiplet's SIP connector. The first one in the returned list is the designated default listening point (the same listening point returned by getListeningPointDefault()).

Returns:

ArrayList of javax.sip.ListeningPoint.

hasAddress

public final boolean hasAddress(java.lang.String host,
                                int port)

Indicates if this jiplet's SIP connector is handling (owns) the given host/port or not. If this jiplet's SIP connector has a listening point (as configured by the jip-port entries in the server.xml file) for the given host and port, then this method returns true.

Parameters:

host - The host address.

port - The port number.

Returns:

true if the given parameters match a listening point associated with this jiplet.

getConnectorProperty

public final JipConnector getConnectorProperty()

Gets the property of the connector to which this jiplet object is attached to.

Returns:

the property of the connector

getInitParams

protected final java.util.HashMap getInitParams()

Returns the init paramters that has been specified in the jip.xml file.

Returns:

Returns the initParams.

setInitParams

protected final void setInitParams(java.util.HashMap initParams)

Parameters:

initParams - The initParams to set.

getDialog

public final JipletDialog getDialog(javax.sip.Dialog dialog,
                                    boolean create)

This method is used to get a JipletDialog object. The JipletDialog is used for storing dialog scope objects. The dialog scope variables are active as long as a SIP dialog is active. For more details on SIP dialog, please refer to the SIP and JAIN-SIP documentation.

Note that the Jiplet Container uses the JAIN-SIP dialog's application data object for stroring the dialog scope variables. Therefore, the jiplet application must not use the application data.

Parameters:

dialog - the JAIN-SIP dialog object

create - true if the JipletDialog object is to be created if it does not exist.

Returns:

the JipletDialog object. If the create parameter is set to true and the dialog scope variables do not exit, null is returned.

registerForResponse

public final JipletTransaction registerForResponse(javax.sip.message.Request request,
                                                   long timeout)

This method is used by the server to register for a SIP response message. When a SIP request message is received by the container, it routes the message to one or more jiplets based on the selection criteria specified in jip.xml. In response, the jiplet may send a SIP request message to another SIP UAC or UAS using the JAIN-SIP API. To tell the container that it expects a response for the request it sent, this method must be used. Note that if this method is not called, the response will not be received by the jiplet.

Parameters:

request - JAIN-SIP request message object

timeout - Timeout duration in millisconds for the response to be received.

Returns:

The transaction object. This object is used if the response is to be cancelled or to set transaction-scope variables.

registerForResponse

public final JipletTransaction registerForResponse(javax.sip.message.Request request)

This method is similar to the registerForResponse(Request request, long timeout) except that it does not have a timeout parameter. It is used when the response message does not have to be received within a set time period. Note that if the jiplet uses this method, it is the responsibility of the jiplet code to free up resources by calling cancelResponse() if no response is received .

Parameters:

request -

Returns:

a transaction object. This object can be used to cancelResponse()

cancelResponse

public final void cancelResponse(JipletTransaction transaction)

This method is used to notify the jiplet container that the response is no longer expected. The container frees up the resources linked to the request-response transaction.

Parameters:

transaction - the transaction id returned by the registerForResponse() methods.

toString

public final java.lang.String toString()

Overrides:

toString in class java.lang.Object

processSignal

public void processSignal(JipletSignal signal)

This method is called by the jiplet container to notify the jiplet of an event (signal) from an external entity. An external entity can send a signal by calling the org.cafesip.jiplet.JipletContext.sendSignal() method. For more details:

Parameters:

signal - contains more detailed information on the signal.

See Also:

JipletSignal